openapi: 3.0.3
servers:
  - url: https://api.rm.smartsheet.com/api/v1
info:
  title: Resource Management OpenAPI Reference
  version: v1
  description: >
    Welcome to the OpenAPI reference documentation for Resource Management by
    Smartsheet!
  contact:
    name: Support
    url: https://help.smartsheet.com/contact
tags:
  - name: api tokens
    x-displayName: API tokens
    description: >
      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](https://help.smartsheet.com/contact/resource-management?_gl=1*1sd27k8*_gcl_au*ODIwNjIyNTE4LjE3NTIxNzA4NTk.*_ga*MTY0NjQ3MjUxLjE3Mzc3NTIxOTI.*_ga_ZYH7XNXMZK*czE3NTg2NzU0NjAkbzQzJGcxJHQxNzU4Njc1NDczJGo0NyRsMCRoMA..)
      if API Token Management is not enabled for your organization. The first
      generated token for an organization has a set “primary” title.
  - name: approvals
    x-displayName: Approvals
    description: >
      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](/api/resource_management/openapi/time-entries) or [expense
      items](/api/resource_management/openapi/expense-items) are “submitted for
      approval.”
  - name: assignables
    x-displayName: Assignables
    description: >
      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:


      - [Projects](/api/resource_management/openapi/projects) (excluding Phases)

      - [Leave types](/api/resource_management/openapi/leave-types)


      > **Note:** Although Phases are projects and are assignable, they are
      inaccessible from the assignables endpoints. Instead, you must access
      Phases the [Projects endpoints](/api/resource_management/openapi/projects)
      or [Phases endpoints](/api/resource_management/openapi/phases).


      It is useful to understand the Assignables API entity because the
      [Assignments endpoints](/api/resource_management/openapi/assignments)
      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](/api/resource_management/openapi/projects), and if a LeaveType,
      the return value looks exactly like what is returned by the [Leave types
      endpoints](/api/resource_management/openapi/leave-types). In both cases,
      the return value has a `type` property, which will be either `Project` or
      `LeaveType`, respectively (phases also have the type `Project`).
  - name: assignments
    x-displayName: Assignments
    description: >
      Assignments connect a [User](/api/resource_management/openapi/users) to a
      [Project](/api/resource_management/openapi/projects) or a
      [Phase](/api/resource_management/openapi/phases) (part of a project) or a
      [LeaveType](/api/resource_management/openapi/leave-types).
  - name: assignments_per_project
    x-displayName: Assignments per project
    description: >
      These assignment operations center on the applicable
      [Project](/api/resource_management/openapi/projects),
      [Phase](/api/resource_management/openapi/phases), or
      [LeaveType](/api/resource_management/openapi/leave-types).
  - name: assignments_per_user
    x-displayName: Assignments per user
    description: |
      These assignment operations center on the assignee.
  - name: assignments_with_subtasks
    x-displayName: Assignments with subtasks
    description: >
      These assignment operations support adding assignments with subtasks and
      showing subtask completion counts.
  - name: availabilities
    x-displayName: Availabilities
    description: >
      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.
  - name: bill_rates
    x-displayName: Bill rates
    description: >
      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](/api/resource_management/openapi/phases) 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.
  - name: budget_item_categories
    x-displayName: Budget item categories
    description: >
      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.
  - name: budget_items
    x-displayName: Budget items
    description: >
      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.
  - name: custom_fields
    x-displayName: Custom fields
    description: >
      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.
  - name: custom_field_values_per_project
    x-displayName: Custom field values per project
    description: >
      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`
  - name: custom_field_values_per_user
    x-displayName: Custom field values per user
    description: >
      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`
  - name: disciplines
    x-displayName: Disciplines
    description: >
      Endpoints for reading organization-defined resource disciplines. You must
      create and manage disciplines via the application UI.
  - name: expense items
    x-displayName: Expense items
    description: >
      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.
  - name: holidays
    x-displayName: Holidays
    description: >
      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.
  - name: leave types
    x-displayName: Leave types
    description: >
      LeaveType is a subclass of
      [Assignables](/api/resource_management/openapi/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.
  - name: phases
    x-displayName: Phases
    description: >
      Phases are a flexible way to break a project into different work stages.


      The Phase class is a subclass of
      [Project](/api/resource_management/openapi/projects), which is a subclass
      of [Assignable](/api/resource_management/openapi/assignables).


      > **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`.
  - name: placeholder resources
    x-displayName: Placeholder resources
    description: >
      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/resource_management/openapi/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/resource_management/openapi/time-entries) API by passing the
      `placeholder_resource_ID` as the `user_id` parameter, similar to
      [assignments](/api/resource_management/openapi/assignments).


      >**Note:** Expense items aren't available for placeholders. Tags for
      placeholders are also not supported. Use custom fields instead.
  - name: project_members
    x-displayName: Project members
    description: >
      These operations support setting, viewing, updating, and removing a
      project's members.
  - name: project_memberships
    x-displayName: Project memberships
    description: >
      These operations support setting, viewing, updating, and removing user
      membership to projects.
  - name: projects
    x-displayName: Projects
    description: >
      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](/api/resource_management/openapi/assignables). Sub-projects
      share the same data model and are called
      [phases](/api/resource_management/openapi/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](/api/resource_management/openapi/projects/postprojects) or
      [Update project](/api/resource_management/openapi/projects/putprojectsid).
  - name: reports
    x-displayName: Reports API
    description: >
      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.
  - name: roles
    x-displayName: Roles
    description: >
      Endpoints for reading organization-defined resource roles. Roles must be
      created and managed via the application UI.
  - name: status options
    x-displayName: Status options
    description: >
      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.
  - name: subtasks
    x-displayName: Subtasks
    description: >
      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](/api/resource_management/openapi/assignments_with_subtasks/getprojectsprojectidassignments)
      operation.
  - name: tags per project
    x-displayName: Tags per project
    description: >
      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.
  - name: tags per user
    x-displayName: Tags per user
    description: >
      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.
  - name: time entries
    x-displayName: Time entries
    description: >
      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.
  - name: user statuses
    x-displayName: User status
    description: >
      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
  - name: users
    x-displayName: Users
    description: >
      The users collection allows you to access information about all users in
      the account.
  - name: users per project
    x-displayName: Users per project
    description: >
      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.
  - name: webhooks
    x-displayName: Webhooks
    description: >
      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](./guides/webhooks.md).
paths:
  /api_tokens:
    servers:
      - url: https://api.rm.smartsheet.com/api
    get:
      summary: List API tokens
      operationId: ListAPITokens
      description: Returns a list of API tokens for your organization.
      tags:
        - api tokens
      responses:
        '200':
          description: A list of API tokens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APITokensResponse'
              example:
                data:
                  - id: 1
                    title: primary
                    token: <token_string>
                  - id: 2
                    title: secondary
                    token: <token_string>
                  - id: 3
                    title: null
                    token: <token_string>
        '404':
          description: Not found.
    post:
      summary: Create API token
      operationId: CreateAPIToken
      description: Create additional API tokens for your organization.
      tags:
        - api tokens
      parameters:
        - in: query
          name: title
          schema:
            type: string
          description: An identifier for the token. It can't be “primary”.
          example: new_token
          required: false
      responses:
        '201':
          description: The token was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIToken'
              example:
                id: 123456
                token: <new_token_string>
                title: new_token
        '404':
          description: Not found.
  /api_tokens/{id}:
    servers:
      - url: https://api.rm.smartsheet.com/api
    put:
      summary: Update API token
      operationId: UpdateAPIToken
      description: Update the title of the given token.
      tags:
        - api tokens
      parameters:
        - in: path
          name: id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the API token.
        - in: query
          name: title
          schema:
            type: string
          description: An identifier for a token. It can't be “primary”.
          example: updated_token
          required: true
      responses:
        '200':
          description: The token was updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIToken'
              example:
                id: 1
                title: updated_token
                token: <token_string>
        '404':
          description: The token ID was not found.
    delete:
      summary: Delete API token
      operationId: DeleteAPIToken
      description: Deletes the given token.
      tags:
        - api tokens
      parameters:
        - in: path
          name: id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the API token.
      responses:
        '200':
          description: The token was deleted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Token deleted.
        '404':
          description: The token ID was not found.
  /api_tokens/renew/{id}:
    servers:
      - url: https://api.rm.smartsheet.com/api
    post:
      summary: Renew API token
      operationId: RenewAPIToken
      description: Deletes the given token and creates a new token.
      tags:
        - api tokens
      parameters:
        - in: path
          name: id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the API token.
      responses:
        '200':
          description: The token was renewed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIToken'
              example:
                id: 1
                token: <new_token_string>
                title: primary
        '404':
          description: The token ID was not found.
  /approvals:
    get:
      summary: List approvals
      operationId: ListApprovals
      description: >
        Lists all submitted time entry and expense item approvals for the
        organization.


        A more typical scenario is to include approvals when getting time
        entries or expense items by specifying `fields=approvals` as a query
        parameter on the respective endpoints.
      tags:
        - approvals
      parameters:
        - in: query
          name: per_page
          schema:
            $ref: '#/components/schemas/perPage'
        - in: query
          name: page
          schema:
            $ref: '#/components/schemas/page'
        - in: query
          name: fields
          schema:
            type: string
            enum:
              - approvables
          description: >-
            If set to `approvables`, includes the full detail of the approved
            TimeEntry or ExpenseItem in the response.
      responses:
        '200':
          description: A paginated list of approval records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovalsResponse'
              examples:
                ApprovalsPopulated:
                  summary: Successful response with pending approval records.
                  value:
                    paging:
                      per_page: 20
                      page: 1
                      previous: null
                      self: /api/v1/approvals?&page=1
                      next: null
                    data:
                      - id: 77326146
                        status: pending
                        approvable_id: 22945507745
                        approvable_type: TimeEntry
                        submitted_by: 1543851
                        submitted_at: '2025-09-29T23:44:09Z'
                        approved_by: null
                        approved_at: null
                        created_at: '2025-09-29T23:44:09Z'
                        updated_at: '2025-09-29T23:44:09Z'
                ZeroApprovalsProcessed:
                  summary: >-
                    Successful processing with zero approvals created. The
                    concurrency check likely failed.
                  value:
                    paging:
                      per_page: 0
                      page: 1
                      previous: null
                      self: /api/v1/approvals?&page=1
                      next: null
                    data: []
    post:
      summary: Create approvals
      operationId: CreateApprovals
      description: >
        Approvals are not created or updated directly. Rather, approvable
        records are submitted or approved through this POST request.


        > **Note:** Only administrators and portfolio editors can approve
        records. API users can only submit records (set status to `pending`),
        but not approve them.
      tags:
        - approvals
      requestBody:
        description: An array of approvable objects and the desired status change.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApprovalProcessRequest'
            example:
              approvables:
                - id: 22945507745
                  type: TimeEntry
                  updated_at: '2025-09-11T18:57:40Z'
              status: pending
      responses:
        '200':
          description: The approval requests were successfully processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovalsResponse'
              examples:
                ApprovalsCreated:
                  summary: |
                    Approval successfully created and submitted. Status: pending
                  value:
                    paging:
                      per_page: 20
                      page: 1
                      previous: null
                      self: /api/v1/approvals?&page=1
                      next: null
                    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'
                ZeroApprovalsProcessed:
                  summary: >-
                    Successful processing with zero approvals created. The
                    concurrency check likely failed.
                  value:
                    paging:
                      per_page: 0
                      page: 1
                      previous: null
                      self: /api/v1/approvals?&page=1
                      next: null
                    data: []
        '400':
          description: >-
            Bad Request. Invalid input, status, or outdated `updated_at`
            timestamp.
        '403':
          description: >-
            Access denied due to insufficient permissions or inability to access
            the specified records.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: forbidden
                  errors:
                    type: array
                    items:
                      type: string
              examples:
                AccessDenied:
                  summary: Insufficient Permission
                  value:
                    message: forbidden
                    errors:
                      - access denied
                ApprovableNotFound:
                  summary: Record Not Found or Inaccessible
                  value:
                    message: forbidden
                    errors:
                      - Approvable Not Found
  /approvals/{approval_id}:
    delete:
      summary: Delete approval
      operationId: DeleteApproval
      description: >
        Deletes a pending approval record. Approvals can only be deleted if the
        status is `pending`.
      tags:
        - approvals
      parameters:
        - in: path
          name: approval_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the approval record to delete.
      responses:
        '200':
          description: The approval record was successfully deleted.
          content:
            application/json:
              schema:
                type: object
        '404':
          description: The approval record was not found or is not pending.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
  /assignables:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
    get:
      summary: List assignables
      operationId: getAssignables
      tags:
        - assignables
      description: Lists the accessible assignables.
      parameters:
        - in: query
          name: per_page
          schema:
            $ref: '#/components/schemas/perPage'
        - in: query
          name: page
          schema:
            $ref: '#/components/schemas/page'
      responses:
        '200':
          description: |
            The accessible assignables.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      oneOf:
                        - $ref: '#/components/schemas/AssignableLeaveType'
                        - $ref: '#/components/schemas/AssignableProject'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /assignables/{assignable_id}:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: assignable_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
    get:
      summary: Fetch assignable
      operationId: getAssignablesId
      tags:
        - assignables
      description: |
        Returns the matching assignable.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AssignableLeaveType'
                  - $ref: '#/components/schemas/AssignableProject'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /assignments:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
    get:
      summary: List assignments
      operationId: getAssignments
      tags:
        - assignments
      description: Lists the accessible assignments.
      parameters:
        - in: query
          name: per_page
          schema:
            $ref: '#/components/schemas/perPage'
        - in: query
          name: page
          schema:
            $ref: '#/components/schemas/page'
        - in: query
          name: from
          schema:
            type: string
            format: date
          description: Filter on assignments that end after this date.
        - in: query
          name: to
          schema:
            type: string
            format: date
          description: Filter on assignments that start before this date.
        - in: query
          name: with_phases
          schema:
            type: boolean
            default: false
          description: If `true`, include assignments to phases. Otherwise, exclude them.
      responses:
        '200':
          description: |
            The accessible assignments.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      allOf:
                        - $ref: '#/components/schemas/Assignment'
                        - type: object
                          properties:
                            subtasks:
                              type: object
                              properties:
                                paging:
                                  $ref: '#/components/schemas/PagingMetadata'
                                data:
                                  type: array
                                  items:
                                    $ref: '#/components/schemas/Subtask'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    post:
      operationId: postAssignments
      summary: Create assignment
      description: >
        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](/api/resource_management/openapi/subtasks).

        >

        > ```json

        > {

        >  "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

        >    }

        >  ]

        >}

        >```
      tags:
        - assignments
        - assignments_with_subtasks
      requestBody:
        description: |
          The property values to apply to a new assignment. 
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Assignment'
                - type: object
                  required:
                    - user_id
                    - assignable_id
                  properties:
                    user_id:
                      type: integer
                      format: int64
                      minimum: 1
                      example: 5612
                      description: The ID of the user this assignment belongs to.
                    assignable_id:
                      type: integer
                      format: int64
                      minimum: 1
                      example: 1234
                      description: >-
                        The ID of the project, phase, or leave type to which the
                        the assignment applies.
                - type: object
                  properties:
                    subtasks:
                      type: array
                      items:
                        type: object
                        properties:
                          description:
                            type: string
                            example: Assess risks
                            description: Identifies the subtask.
                          completed:
                            type: boolean
                            example: false
                            description: >-
                              This is true if the subtask is done; otherwise,
                              it's false.
      responses:
        '200':
          description: |
            The new assignment.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Assignment'
                  - type: object
                    properties:
                      subtasks:
                        type: object
                        properties:
                          paging:
                            $ref: '#/components/schemas/PagingMetadata'
                          data:
                            type: array
                            items:
                              $ref: '#/components/schemas/Subtask'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /assignments/{assignment_id}:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: assignment_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 889
    get:
      summary: Fetch assignment
      operationId: getAssignmentsId
      tags:
        - assignments
      description: |
        Returns the matching assignment.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AssignmentPercentAllocation'
                  - $ref: '#/components/schemas/AssignmentFixedHoursAllocation'
                  - $ref: '#/components/schemas/AssignmentHoursPerDayAllocation'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    put:
      operationId: putAssignmentsAssignmentId
      summary: Update assignment
      description: >
        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`
      tags:
        - assignments
      requestBody:
        description: |
          The property values to apply to the assignment. 
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Assignment'
      responses:
        '200':
          description: |
            The updated assignment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assignment'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    delete:
      operationId: deletetAssignmentsAssignmentId
      summary: Delete assignment
      description: |
        Deletes the matching assignment.
      tags:
        - assignments
      responses:
        '200':
          description: |
            An empty object.
          content:
            application/json:
              schema:
                type: object
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /bill_rates:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
    get:
      summary: List bill rates
      operationId: getBillRates
      tags:
        - bill_rates
      description: Lists the accessible bill rates.
      parameters:
        - in: query
          name: per_page
          schema:
            $ref: '#/components/schemas/perPage'
        - in: query
          name: page
          schema:
            $ref: '#/components/schemas/page'
      responses:
        '200':
          description: |
            The accessible bill rates.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BillRate'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /bill_rates/{bill_rate_id}:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: bill_rate_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
    get:
      summary: Fetch bill rate
      operationId: getBillRatesId
      tags:
        - bill_rates
      description: Returns the matching accessible bill rate.
      responses:
        '200':
          description: |
            The matching accessible bill rate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillRate'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /budget_items/{budget_item_id}:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: budget_item_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
    get:
      summary: Fetch budget item
      operationId: getBudgetItem
      tags:
        - budget_items
      description: Get the matching budget item.
      responses:
        '200':
          description: |
            The matching budget item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetItem'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    put:
      operationId: putBudgetItem
      summary: Update budget item
      description: |
        Updates the matching budget item.
      tags:
        - budget_items
      requestBody:
        description: The property values to apply to the matching budget item.
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/BudgetItem'
                - type: object
                  properties:
                    assignable_id:
                      type: integer
                      format: int64
                      minimum: 1
                      description: >-
                        Unique identifier of the assignable item to which the
                        budget is assigned.
                      example: 821065
      responses:
        '200':
          description: |
            The updated budget item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetItem'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    delete:
      summary: Delete budget item
      operationId: deleteBudgetItem
      tags:
        - budget_items
      description: Deletes the matching budget item.
      responses:
        '200':
          description: |
            An empty object.
          content:
            application/json:
              schema:
                type: object
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /custom_fields:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
    get:
      summary: List custom fields
      operationId: getCustomFields
      tags:
        - custom_fields
      description: Lists the accessible custom fields.
      parameters:
        - in: query
          name: per_page
          schema:
            $ref: '#/components/schemas/perPage'
        - in: query
          name: page
          schema:
            $ref: '#/components/schemas/page'
        - in: query
          name: namespace
          schema:
            $ref: '#/components/schemas/CustomFieldNamespace'
          required: true
      responses:
        '200':
          description: |
            The accessible custom fields.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomField'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    post:
      operationId: postCustomFields
      summary: Create custom field
      description: |
        Creates a custom field.
      tags:
        - custom_fields
      requestBody:
        description: |
          The property values to apply to a new custom field. 
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/CustomField'
                - type: object
                  required:
                    - name
                    - namespace
                    - data_type
                  properties:
                    name:
                      type: string
                      description: The name of the custom field.
                      example: Skills
                    namespace:
                      $ref: '#/components/schemas/CustomFieldNamespace'
                    data_type:
                      $ref: '#/components/schemas/CustomFieldDataType'
                    apply_default_to_existing_objects:
                      type: boolean
                      description: >-
                        if `true`, this triggers a one-time application of the
                        default value to all existing projects or users.
      responses:
        '200':
          description: |
            The new custom field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomField'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /custom_fields/{custom_field_id}:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: custom_field_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 889
    get:
      summary: Fetch custom field
      operationId: getCustomFieldsId
      tags:
        - custom_fields
      description: |
        Returns the matching custom field.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignmentPercentAllocation'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    put:
      operationId: putCustomFieldsCustomFieldId
      summary: Update custom field
      description: |
        Updates a custom field.

        Editable properties:

        - `name` 
        - `description` 
        - `options` 
        - `default_value` 
        - `is_visible_on_info_page`
        - `is_visible_as_filter`
      tags:
        - custom_fields
      requestBody:
        description: |
          The property values to apply to the custom field. 

          Editable properties:

          - `name` 
          - `description` 
          - `options` 
          - `default_value` 
          - `is_visible_on_info_page`
          - `is_visible_as_filter`
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/CustomField'
      responses:
        '200':
          description: |
            The updated custom field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomField'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    delete:
      operationId: deletetCustomFieldsCustomFieldId
      summary: Delete custom field
      description: >
        Deletes the matching custom field.


        > **Warning:** Deleting a custom field will also delete all of its
        associated custom field values.
      tags:
        - custom_fields
      responses:
        '200':
          description: |
            An empty object.
          content:
            application/json:
              schema:
                type: object
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /disciplines:
    get:
      summary: List disciplines
      operationId: ListDisciplines
      description: Retrieves a paginated list of all accessible disciplines.
      tags:
        - disciplines
      parameters:
        - in: query
          name: filter
          schema:
            type: string
          description: >-
            Respects standard filtering parameters (check documentation for
            supported fields).
        - in: query
          name: per_page
          schema:
            type: integer
            default: 20
            maximum: 1000
          description: Parameters for pagination.
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: Parameters for pagination.
      responses:
        '200':
          description: A paginated list of discipline objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisciplinesResponse'
              example:
                paging:
                  per_page: 20
                  page: 1
                  previous: null
                  self: /api/v1/disciplines?&page=1
                  next: null
                data:
                  - id: 8663423
                    value: Strategy & Transformation
                  - id: 8663424
                    value: Learning & Content
                  - id: 8663425
                    value: Product Readiness
        '404':
          description: The discipline ID was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
  /disciplines/{discipline_id}:
    get:
      summary: Fetch discipline
      operationId: FetchDiscipline
      description: Returns the discipline with the matching ID.
      tags:
        - disciplines
      parameters:
        - in: path
          name: discipline_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the discipline.
      responses:
        '200':
          description: The matching discipline object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Discipline'
              example:
                id: 1
                value: Developer
        '404':
          description: The approval record was not found or is not pending.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
  /expense_item_categories:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
    get:
      summary: List expense item categories
      operationId: getExpenseBudgetItemCategories
      tags:
        - budget_item_categories
      description: |
        Lists the accessible, account-level expense budget item categories. 

        > **Note:** Project-specific categories aren't included.
      parameters:
        - in: query
          name: per_page
          schema:
            $ref: '#/components/schemas/perPage'
        - in: query
          name: page
          schema:
            $ref: '#/components/schemas/page'
      responses:
        '200':
          description: |
            The accessible, account-level expense budget item categories.

            > **Note:** Project-specific categories aren't included.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BudgetItemCategory'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /holidays:
    get:
      summary: List holidays
      operationId: getHolidays
      tags:
        - holidays
      description: |
        Retrieves a paginated list of holidays.
      parameters:
        - in: query
          name: per_page
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 1000
            default: 20
          description: |
            The number of items to return per page.
                Defaults to 20. Can't exceed 1,000.
          example: 50
          required: false
        - in: query
          name: page
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 20
          description: |
            The page number to retrieve.
            Defaults to 1, which is the first page.
          example: 2
          required: false
      responses:
        '200':
          description: The root response object for a paginated list of holidays.
          content:
            application/json:
              schema:
                type: object
                required:
                  - paging
                  - data
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/HolidayItem'
              examples:
                sampleHolidaysResponse:
                  summary: Example paginated holidays response
                  value:
                    paging:
                      per page: 20
                      page: 1
                      previous: null
                      self: /api/v1/holidays?&page=1
                      next: null
                    data:
                      - id: 83019
                        date: '2022-05-30'
                        name: Memorial day
                        created_at: '2022-03-23T16:58:29Z'
                        updated_at: '2022-03-23T16:58:29Z'
                      - id: 83020
                        date: '2022-06-20'
                        name: Juneteenth
                        created_at: '2022-03-23T16:58:46Z'
                        updated_at: '2022-03-23T16:58:46Z'
  /leave_types:
    get:
      summary: List leave types
      operationId: getLeaveTypes
      description: Retrieves a paginated list of available leave types.
      tags:
        - leave types
      responses:
        '200':
          description: A list of LeaveType objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaveTypesResponse'
              example:
                paging:
                  next: null
                  page: 1
                  per_page: 20
                  previous: null
                  self: /api/v1/leave_types?per_page=20&page=1
                data:
                  - id: 2
                    description: null
                    guid: FAFC777B-8CD2-4434-9C0E-59366A1A65B9
                    name: Sick
                    deleted_at: null
                    created_at: '2013-09-10T21:31:06Z'
                    updated_at: '2013-09-10T21:31:06Z'
                    type: LeaveType
  /leave_types/{leave_type_id}:
    get:
      summary: Fetch leave type
      operationId: getLeaveTypeId
      description: Retrieves a single leave type by its ID.
      tags:
        - leave types
      parameters:
        - in: path
          name: leave_type_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the leave type.
      responses:
        '200':
          description: The requested LeaveType object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaveType'
              example:
                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'
                type: LeaveType
                uid: leavetype-1234567
        '404':
          description: The leave type was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
  /placeholder_resources:
    get:
      summary: List placeholder resources
      operationId: ListPlaceholderResources
      description: |
        Retrieves a paginated list of all placeholder resources in the account.
      tags:
        - placeholder resources
      parameters:
        - in: query
          name: fields
          schema:
            type: string
            enum:
              - assignments
              - custom_field_values
          description: >-
            A comma-separated list of additional fields to include in the
            response. Custom field values require a Pro plan or higher.
          example: assignments
        - in: query
          name: per_page
          schema:
            type: integer
            default: 20
            maximum: 1000
          description: Parameters for pagination.
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: Parameters for pagination.
        - in: query
          name: with_deleted
          schema:
            type: boolean
          description: If set to `true`, includes resources flagged as deleted.
      responses:
        '200':
          description: A list of placeholder resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceholderResourcesResponse'
              example:
                paging:
                  per_page: 20
                  page: 1
                  previous: null
                  self: /api/v1/placeholder_resources?&page=1
                  next: null
                data:
                  - id: 1543853
                    title: IT Admin
                    user_type_id: 0
                    guid: 337e802d-30b8-4abe-a021-0c66e64ba326
                    role: null
                    discipline: null
                    location: null
                    displayName: IT Admin
                    type: PlaceholderResource
                    thumbnail: https://assets.rm.smartsheet.com/images/it_admin.png
                    abbreviation: IT
                    color: Fuchsia
                    created_at: '2022-03-22T18:56:10Z'
                    updated_at: '2022-04-05T19:47:27Z'
                    billrate: -1
                    assignments:
                      paging:
                        self: /api/v1/users/1543853/assignments?per_page=0&page=1
                        next: null
                        previous: null
                        page: 1
                        per_page: 0
                      data: []
                  - id: 1543854
                    title: Account Finance
                    user_type_id: 0
                    guid: 008eedb3-74c9-4e59-9333-d25ded8b29ff
                    role: null
                    discipline: null
                    location: null
                    displayName: Account Finance
                    type: PlaceholderResource
                    thumbnail: >-
                      https://assets.rm.smartsheet.com/images/account_finance.png
                    abbreviation: FIN
                    color: Blue
                    created_at: '2022-03-22T18:56:10Z'
                    updated_at: '2022-04-05T18:45:15Z'
                    billrate: -1
                    assignments:
                      paging:
                        self: /api/v1/users/1543854/assignments?per_page=0&page=1
                        next: null
                        previous: null
                        page: 1
                        per_page: 0
                      data: []
        '404':
          description: Not Found.
    post:
      summary: Create placeholder resource
      operationId: CreatePlaceholderResource
      description: >
        Creates a new placeholder resource. The `title` is required as it is the
        name displayed in the application UI.
      tags:
        - placeholder resources
      requestBody:
        description: The properties for the new placeholder resource.
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PlaceholderCreateRequest'
            example:
              title: Designer
              role: Design Lead
      responses:
        '200':
          description: The placeholder was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Placeholder'
              example:
                id: 4074761
                title: RM Test Placeholder
                user_type_id: 0
                guid: 1ce497c5-64a2-4a19-9983-6c3c4783f6e8
                role: null
                discipline: null
                location: null
                displayName: RM Test Placeholder
                type: PlaceholderResource
                thumbnail: null
                abbreviation: null
                color: null
                created_at: '2025-09-26T18:54:02Z'
                updated_at: '2025-09-26T18:54:02Z'
                billrate: -1
        '403':
          description: Bad request. The required `title` parameter is missing or invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: bad data
                  errors:
                    type: array
                    items:
                      type: string
              examples:
                MissingTitle:
                  summary: Missing Title or Malformed Data
                  value:
                    message: bad data
                    errors:
                      - Title is too short (minimum is 1 character)
                      - >-
                        First name Backslashes are not allowed, and single
                        quotes or apostrophes are not allowed as the first
                        character.
  /placeholder_resources/{placeholder_resource_id}:
    get:
      summary: Fetch placeholder resource
      operationId: FetchPlaceholderResource
      description: Retrieves a single placeholder resource by its ID.
      tags:
        - placeholder resources
      parameters:
        - in: path
          name: placeholder_resource_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the placeholder resource.
        - in: query
          name: fields
          schema:
            type: string
            enum:
              - assignments
              - custom_field_values
          description: >-
            A comma-separated list of additional fields to include in the
            response.
          example: assignments
      responses:
        '200':
          description: The requested placeholder resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Placeholder'
              example:
                id: 4074761
                title: RM Test Placeholder
                user_type_id: 0
                guid: 1ce497c5-64a2-4a19-9983-6c3c4783f6e8
                role: null
                discipline: null
                location: null
                displayName: RM Test Placeholder
                type: PlaceholderResource
                thumbnail: null
                abbreviation: null
                color: null
                created_at: '2025-09-26T18:54:02Z'
                updated_at: '2025-09-26T18:54:02Z'
                billrate: -1
                assignments:
                  paging:
                    self: /api/v1/users/4074761/assignments?per_page=0&page=1
                    next: null
                    previous: null
                    page: 1
                    per_page: 0
                  data: []
        '404':
          description: >-
            The placeholder resource was not found, likely due to an invalid or
            missing ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
    put:
      summary: Update placeholder resource
      operationId: UpdatePlaceholderResource
      description: >-
        Updates the title, role, discipline, or location of an existing
        placeholder resource.
      tags:
        - placeholder resources
      parameters:
        - in: path
          name: placeholder_resource_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the placeholder resource.
      requestBody:
        description: >-
          The fields to update. Only `title` is a required parameter for the PUT
          operation.
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PlaceholderCreateRequest'
            example:
              title: Senior Designer
      responses:
        '200':
          description: The placeholder was updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Placeholder'
              example:
                id: 4074761
                title: Senior Designer
                user_type_id: 0
                guid: 1ce497c5-64a2-4a19-9983-6c3c4783f6e8
                role: null
                discipline: null
                location: null
                displayName: Senior Designer
                type: PlaceholderResource
                thumbnail: null
                abbreviation: null
                color: null
                created_at: '2025-09-26T18:54:02Z'
                updated_at: '2025-09-26T19:12:54Z'
                billrate: -1
        '404':
          description: >-
            The placeholder resource was not found, likely due to an invalid or
            missing ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
    delete:
      summary: Delete placeholder resource
      operationId: DeletePlaceholderResource
      description: |
        Deletes the placeholder resource.

        >**Note:** Time tracking for placeholders is not supported.
      tags:
        - placeholder resources
      parameters:
        - in: path
          name: placeholder_resource_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the placeholder resource.
      responses:
        '204':
          description: The placeholder resource was successfully deleted.
          content:
            application/json:
              schema:
                type: object
        '404':
          description: >-
            The placeholder resource was not found, likely due to an invalid or
            missing ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
  /placeholder_resources/{placeholder_resource_id}/assignments:
    get:
      summary: List placeholder resource assignments
      operationId: ListPlaceholderResourceAssignments
      description: >
        Retrieves a list of assignments for a specific placeholder. A
        `placeholder_resource_ID` is used as the `user_id` parameter in the
        [Assignments](/api/resource_management/openapi/assignments) API.
      tags:
        - placeholder resources
      parameters:
        - in: path
          name: placeholder_resource_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the placeholder resource.
      responses:
        '200':
          description: >-
            A paginated list of assignments. Returns an empty array if no
            assignments are found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignmentsResponse'
        '404':
          description: >-
            The placeholder resource was not found, likely due to an invalid or
            missing ID.
          content:
            text/plain:
              schema:
                type: string
                example: Not Found
  /projects:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
    get:
      summary: List projects
      operationId: getProjects
      tags:
        - projects
      description: Lists the accessible projects.
      parameters:
        - in: query
          name: from
          schema:
            type: string
            format: date
          description: |
            Get projects that end on or after this date.
        - in: query
          name: to
          schema:
            type: string
            format: date
          description: |
            Get projects that start on or before this date.
        - in: query
          name: strict
          schema:
            type: boolean
          description: >
            Set to `true` to restrict the projects to only those contained
            entirely within the `from` and `to` params.
          example: true
        - in: query
          name: fields
          schema:
            type: string
          description: >
            A comma-separated list (no spaces) of additional fields to include
            with each project in the response. Here are the optional values:
            "children", "tags", "budget_items", "project_state" , "phase_count",
            "summary", "custom_field_values"
          example: >-
            children,tags,custom_field_values,budget_items,project_state,phase_count,summary,custom_field_values
        - in: query
          name: filter_field
          schema:
            type: string
            enum:
              - project_state
          description: >
            Specifies the property to filter on. "project_state" is the only
            supported value.
          example: project_state
        - in: query
          name: filter_list
          schema:
            type: string
          description: >
            The value of "filter_field" to match, outputs will be projects with
            state matching this value. Possible values: Internal, Tentative,
            Confirmed
        - in: query
          name: sort_field
          description: |
            A project field on which to sort the projects in the response. 
          schema:
            type: string
            enum:
              - created
              - updated
          example: created
        - in: query
          name: sort_order
          description: The order for sorting the results based on the `sort_field`.
          schema:
            type: string
            enum:
              - ascending
              - descending
          example: ascending
        - in: query
          name: project_code
          schema:
            type: string
          description: |
            Project code to match exactly.
        - in: query
          name: phase_name
          schema:
            type: string
          description: >
            [Phase](/api/resource_management/openapi/phases) name to match
            exactly.
        - in: query
          name: with_archived
          description: If set to `true`, includes archived projects.
          schema:
            type: boolean
          example: true
        - in: query
          name: with_phases
          schema:
            type: boolean
          description: |
            Set to `true`` to include phases (child projects).
          example: true
        - in: query
          name: archived
          schema:
            type: boolean
          description: |
            Set to `true`` to include archived projects.
          example: false
        - in: query
          name: per_page
          schema:
            $ref: '#/components/schemas/perPage'
        - in: query
          name: page
          schema:
            $ref: '#/components/schemas/page'
      responses:
        '200':
          description: |
            The accessible projects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    post:
      operationId: postProjects
      summary: Create project
      description: >
        Creates a project.


        > **Important:** If you want to make the project owner a member, you
        must specify the `owner_id` body parameter set to that user's ID.
      tags:
        - projects
      requestBody:
        description: >
          The property values to apply to a new project. 


          > **Important:** If you want to make the project owner a member, you
          must specify the `owner_id` body parameter set to that user's ID.
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Project'
                - type: object
                  properties:
                    name:
                      type: string
                  required:
                    - name
      responses:
        '200':
          description: |
            The new project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /projects/{project_id}:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: project_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
    get:
      summary: Fetch project
      operationId: getProjectsId
      tags:
        - projects
        - phases
      description: |
        Returns the matching project or phase.
      parameters:
        - in: query
          name: fields
          schema:
            type: string
          description: >
            A comma-separated list (no spaces) of additional response fields to
            include with the matching project or phase. Here are the optional
            values: "children", "tags", "budget_items", "project_state" ,
            "phase_count", "summary", "custom_field_values"
          example: children,custom_field_values
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Project'
                  - $ref: '#/components/schemas/Phase'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    put:
      summary: Update project
      operationId: putProjectsId
      tags:
        - projects
      description: >
        Updates the matching project. 


        > **Note:** You can delete a project by setting `archived` to `true`;
        you can undelete a project by setting `archived` to `false`.


        > **Note:** You can't update archived projects (ones that have
        `archived` set to `true`). You must first unarchive an archived project
        (set `archived` to `false`) before updating its other properties in a
        subsequent request.
      requestBody:
        description: The property values to apply to the matching project.
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Project'
                - type: object
                  properties:
                    archived:
                      type: boolean
                      description: >
                        Set to `true` to archive the project; set to `false` to
                        unarchive the project.


                        **Important:** The archived property must be the only
                        request body property.
                      example: true
                    use_parent_bill_rates:
                      type: boolean
                      description: >
                        If the project has a parent, set `use_parent_bill_rates`
                        to `true` to use the parent project's bill rates; set it
                        to `false` to use project-specific bill rates.  
                      example: true
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Project'
      responses:
        '200':
          description: |
            The updated project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    delete:
      summary: Delete project
      operationId: deleteProjectsId
      tags:
        - projects
      description: |
        Removes the matchig project.  
      responses:
        '200':
          description: |
            Removed the matching project successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    default: true
                  message:
                    type: string
                    enum:
                      - Archived
                    default: Archived
        '404':
          description: |
            Project not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    default: false
                  message:
                    type: string
                    enum:
                      - not found
                    default: not found
        default:
          description: Generic error payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorPayload'
  /projects/{project_id}/assignments:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: project_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
    get:
      summary: List project assignments
      operationId: getProjectsProjectIdAssignments
      tags:
        - assignments_per_project
        - assignments_with_subtasks
        - subtasks
      description: >
        Returns the assignments for the matching project.


        > **Note:** To include subtask completion/total counts for each
        assignment, specify the `fields=subtask_counts` query parameter setting.
      parameters:
        - in: query
          name: per_page
          schema:
            $ref: '#/components/schemas/perPage'
        - in: query
          name: page
          schema:
            $ref: '#/components/schemas/page'
        - in: query
          name: from
          schema:
            type: string
            format: date
          description: Filter on assignments that end on or after this date.
        - in: query
          name: to
          schema:
            type: string
            format: date
          description: Filter on assignments that start on or before this date.
        - in: query
          name: with_phases
          schema:
            type: boolean
            default: false
          description: If `true`, include assignments to phases. Otherwise, exclude them.
        - in: query
          name: fields
          schema:
            type: string
            example: subtask_counts
          description: >
            A comma-separate list of project assignment-related attributes to
            include in the response.


            Supported fields: `subtask_counts`
      responses:
        '200':
          description: The assignments for the matching project.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      allOf:
                        - $ref: '#/components/schemas/Assignment'
                        - type: object
                          properties:
                            subtask_counts:
                              type: object
                              properties:
                                completed:
                                  type: integer
                                  format: int32
                                  minimum: 0
                                  example: 0
                                  description: Number of finished subtasks.
                                total:
                                  type: integer
                                  format: int32
                                  minimum: 0
                                  example: 0
                                  description: Total number of subtasks.
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    post:
      operationId: postProjectsProjectIdAssignments
      summary: Create project assignment
      description: >
        Creates a project assignment.


        Typical parameters:


        - `user_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`)
      tags:
        - assignments_per_project
      requestBody:
        description: |
          The property values to apply to a new project assignment. 
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Assignment'
                - type: object
                  required:
                    - user_id
                  properties:
                    user_id:
                      type: integer
                      format: int64
                      minimum: 1
                      example: 5612
                      description: The ID of the user this assignment belongs to.
      responses:
        '200':
          description: |
            The new project assignment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assignment'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /projects/{project_id}/assignments/{assignment_id}:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: project_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
      - in: path
        name: assignment_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 889
    get:
      summary: Fetch project assignment
      operationId: getProjectsProjectIdAssignmentsId
      tags:
        - assignments_per_project
      description: |
        Returns the matching project assignment.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AssignmentPercentAllocation'
                  - $ref: '#/components/schemas/AssignmentFixedHoursAllocation'
                  - $ref: '#/components/schemas/AssignmentHoursPerDayAllocation'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    put:
      operationId: putProjectsProjectIdAssignmentsAssignmentId
      summary: Update project assignment
      description: >
        Updates the matching project assignment.


        Typical parameters:


        - `user_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`
      tags:
        - assignments_per_project
      requestBody:
        description: |
          The property values to apply to the project assignment. 
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Assignment'
      responses:
        '200':
          description: |
            The updated project assignment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assignment'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    delete:
      operationId: deletetProjectsProjectIdAssignmentsAssignmentId
      summary: Delete project assignment
      description: |
        Deletes the matching project assignment.
      tags:
        - assignments_per_project
      responses:
        '200':
          description: |
            An empty object.
          content:
            application/json:
              schema:
                type: object
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /projects/{project_id}/assignments/{assignment_id}/subtasks:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: project_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
      - in: path
        name: assignment_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 889
    get:
      summary: List subtasks
      operationId: getProjectsProjectIdAssignmentsAssignmentIdSubtasks
      tags:
        - subtasks
      description: Returns the subtasks for the matching project assignment.
      parameters:
        - in: query
          name: per_page
          schema:
            $ref: '#/components/schemas/perPage'
        - in: query
          name: page
          schema:
            $ref: '#/components/schemas/page'
      responses:
        '200':
          description: The subtasks for the matching project assignment.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Subtask'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    post:
      operationId: postProjectsProjectIdAssignmentsAssignmentIdSubtasks
      summary: Create subtask
      description: Creates a subtask.
      tags:
        - subtasks
      requestBody:
        description: The property values to apply to a new subtask.
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Subtask'
                - type: object
                  properties:
                    description:
                      type: string
                      example: Assess risks
                      description: Identifies the subtask.
                  required:
                    - description
      responses:
        '200':
          description: The new subtask.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subtask'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /projects/{project_id}/assignments/{assignment_id}/subtasks/{subtask_id}:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: project_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
      - in: path
        name: assignment_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 889
      - in: path
        name: subtask_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 6789012345
    get:
      summary: Fetch subtask
      operationId: getProjectsProjectIdAssignmentsAssignmentsIdSubtasksSubtaskId
      tags:
        - subtasks
      description: Returns the matching subtask.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subtask'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    put:
      operationId: putProjectsProjectIdAssignmentsAssignmentsIdSubtasksSubtaskId
      summary: Update subtask
      description: Updates the matching subtask.
      tags:
        - subtasks
      requestBody:
        description: The property values to apply to the subtask.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Subtask'
      responses:
        '200':
          description: The updated subtask.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subtask'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    delete:
      operationId: deletetProjectsProjectIdAssignmentsAssignmentsIdSubtasksSubtaskId
      summary: Delete subtask
      description: |
        Deletes the matching subtask.

        > **Warning:** Deleting a subtask permantently destroys its record.
      tags:
        - subtasks
      responses:
        '200':
          description: An empty object.
          content:
            application/json:
              schema:
                type: object
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /projects/{project_id}/bill_rates:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: project_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
    get:
      summary: List project bill rates
      operationId: listProjectBillRates
      tags:
        - bill_rates
      description: Lists the accessible project bill rates.
      parameters:
        - in: query
          name: per_page
          schema:
            $ref: '#/components/schemas/perPage'
        - in: query
          name: page
          schema:
            $ref: '#/components/schemas/page'
      responses:
        '200':
          description: |
            The accessible project bill rates.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BillRate'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /projects/{project_id}/bill_rates/{bill_rate_id}:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: project_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
      - in: path
        name: bill_rate_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
    get:
      summary: Fetch project bill rate
      operationId: getBillRate
      tags:
        - bill_rates
      description: Get the matching project-specific bill rate.
      responses:
        '200':
          description: |
            The matching project-specific bill rate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillRate'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    put:
      operationId: putProjectBillRate
      summary: Update project bill rate
      description: |
        Updates the matching project bill rate.
      tags:
        - bill_rates
      requestBody:
        description: The property values to apply to the matching project bill rate.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillRate'
      responses:
        '200':
          description: |
            The updated bill rate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillRate'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /projects/{project_id}/custom_field_values:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: project_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
    get:
      summary: List project custom field values
      operationId: getProjectsProjectIdCustomFieldValues
      tags:
        - custom_field_values_per_project
      description: |
        Returns the custom field values for the matching project.
      parameters:
        - in: query
          name: per_page
          schema:
            $ref: '#/components/schemas/perPage'
        - in: query
          name: page
          schema:
            $ref: '#/components/schemas/page'
      responses:
        '200':
          description: The custom field values for the matching project.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomFieldValue'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    post:
      operationId: postProjectsProjectIdCustomFieldValues
      summary: Create project custom field value
      description: |
        Creates a project custom field value.
      tags:
        - custom_field_values_per_project
      requestBody:
        description: The property values to apply to a new project custom field value.
        content:
          application/json:
            schema:
              type: object
              required:
                - custom_field_id
                - value
              properties:
                custom_field_id:
                  type: integer
                  format: int64
                  minimum: 1
                  description: The unique identifier of the custom field.
                value:
                  $ref: '#/components/schemas/CustomFieldValueValue'
      responses:
        '200':
          description: |
            The new project custom field value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldValue'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /projects/{project_id}/custom_field_values/{custom_field_value_id}:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: project_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
      - in: path
        name: custom_field_value_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 889
    get:
      summary: Fetch project custom field value
      operationId: getProjectsProjectIdCustomFieldValuesCustomFieldValuesId
      tags:
        - custom_field_values_per_project
      description: |
        Returns the matching project custom field value.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldValue'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    put:
      operationId: putProjectsProjectIdCustomFieldValuesCustomFieldValueId
      summary: Update project custom field value
      description: |
        Updates the matching project custom field value.
      tags:
        - custom_field_values_per_project
      requestBody:
        description: The property values to apply to the project custom field value.
        content:
          application/json:
            schema:
              type: object
              properties:
                value:
                  $ref: '#/components/schemas/CustomFieldValueValue'
      responses:
        '200':
          description: |
            The updated project custom field value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldValue'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /projects/{project_id}/budget_items:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: project_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
    get:
      summary: List budget items
      operationId: getProjectBudgetItems
      tags:
        - budget_items
      description: Lists the accessible project/phase budget items of the specified type.
      parameters:
        - in: query
          name: item_type
          schema:
            $ref: '#/components/schemas/BudgetItemType'
          required: true
      responses:
        '200':
          description: |
            The accessible budget items.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BudgetItem'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    post:
      operationId: postBudgetItem
      summary: Create budget item
      description: |
        Creates a budget item for the speicified project or phase.
      tags:
        - budget_items
      requestBody:
        description: The property values to apply to a new budget item.
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/BudgetItem'
                - type: object
                  properties:
                    item_type:
                      $ref: '#/components/schemas/BudgetItemType'
                    amount:
                      $ref: '#/components/schemas/BudgetItemAmount'
                  required:
                    - item_type
                    - amount
      responses:
        '200':
          description: |
            The new budget item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetItem'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /projects/{project_id}/budget_items/{budget_item_id}:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: project_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
      - in: path
        name: budget_item_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
    get:
      summary: Fetch project budget item
      operationId: getProjectBudgetItem
      tags:
        - budget_items
      description: Get the matching project/phase budget item.
      responses:
        '200':
          description: |
            The matching budget item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetItem'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    put:
      operationId: putProjectBudgetItem
      summary: Update project budget item
      description: |
        Updates the matching project/phase budget item.
      tags:
        - budget_items
      requestBody:
        description: The property values to apply to the matching budget item.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BudgetItem'
      responses:
        '200':
          description: |
            The updated budget item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetItem'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /projects/{project_id}/expense_items:
    get:
      summary: List project expense items
      operationId: ListProjectExpenseItems
      description: Retrieves a list of expense items reported for a specific project.
      tags:
        - expense items
      parameters:
        - in: path
          name: project_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the project.
        - in: query
          name: from
          schema:
            type: string
            format: date
          description: Get expenses reported on or after this date.
          example: '2017-03-14'
        - in: query
          name: to
          schema:
            type: string
            format: date
          description: Get expenses reported on or before this date.
          example: '2017-03-21'
        - in: query
          name: per_page
          schema:
            type: integer
            default: 20
            maximum: 1000
          description: Parameters for pagination.
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: Parameters for pagination.
      responses:
        '200':
          description: A list of expense items for a project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpenseItemsResponse'
              example:
                paging:
                  per_page: 20
                  page: 1
                  previous: null
                  self: >-
                    /api/v1/projects/6929276/expense_items?assignable_id=6929276&page=1
                  next: null
                data:
                  - id: 517417
                    assignable_id: 6929276
                    assignable_type: Project
                    user_id: 987654
                    amount: 500
                    date: '2025-04-09'
                    category: null
                    notes: null
                    created_at: '2025-09-25T03:12:51Z'
                    updated_at: '2025-09-25T03:12:51Z'
                  - id: 517418
                    assignable_id: 6929276
                    assignable_type: Project
                    user_id: 987654
                    amount: 500
                    date: '2025-04-09'
                    category: null
                    notes: null
                    created_at: '2025-09-25T03:13:12Z'
                    updated_at: '2025-09-25T03:13:12Z'
        '404':
          description: The project ID was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
  /projects/{project_id}/expense_items/{expense_item_id}:
    get:
      summary: Fetch project expense item
      operationId: FetchProjectExpenseItem
      description: Retrieves a single expense item by its ID.
      tags:
        - expense items
      parameters:
        - in: path
          name: project_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the user.
        - in: path
          name: expense_item_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the expense item.
      responses:
        '200':
          description: The requested expense item object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpenseItem'
              example:
                id: 517417
                assignable_id: 6929276
                assignable_type: Project
                user_id: 654321
                amount: 500
                date: '2025-04-09'
                category: null
                notes: null
                created_at: '2025-09-25T03:12:51Z'
                updated_at: '2025-09-25T03:12:51Z'
        '404':
          description: The expense item was not found.
  /projects/{project_id}/expense_item_categories:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: project_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
    get:
      summary: List project expense item categories
      operationId: getProjectExpenseBudgetItemCategories
      tags:
        - budget_item_categories
      description: >-
        Lists the accessible project/phase-specific expense budget item
        categories.
      parameters:
        - in: query
          name: item_type
          schema:
            $ref: '#/components/schemas/BudgetItemCategory'
          required: true
      responses:
        '200':
          description: >
            The accessible project/phase-specific expense budget item
            categories.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BudgetItemCategory'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /projects/{project_id}/project_members:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: project_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier of the parent project instance.
        example: 1234567
    get:
      summary: List project members
      operationId: getProjectsProjectIdProjectMembers
      tags:
        - project_members
      description: Lists the members of the matching project.
      parameters:
        - in: query
          name: membership
          schema:
            type: string
            enum:
              - member
              - viewer
              - reporter
              - scheduler
              - editor
            default: member
          example: member
        - in: query
          name: per_page
          schema:
            $ref: '#/components/schemas/perPage'
        - in: query
          name: page
          schema:
            $ref: '#/components/schemas/page'
      responses:
        '200':
          description: |
            The members of the matching project. 
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectMember'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    post:
      operationId: postProjectsProjectIdProjectMembers
      summary: Set project member list
      description: >
        Sets the project's entire member list, replacing any existing member
        list.


        > **Warning:** This operation replaces the member list. If you leave off
        a user who's a current member, that user is REMOVED from the project.


        If a specified user is already a member of the project, that user's
        membership is changed to the membership level.


        If the user wasn't previously a member of the project, the user is added
        with the specified membership level.
      tags:
        - project_members
      requestBody:
        description: >-
          An object that has a `relationships` field, which is an array of
          `[user_id, membership_level]` tuples.
        content:
          application/json:
            schema:
              type: object
              properties:
                relationships:
                  description: An array of user ID and membership level pairs (tuples).
                  type: array
                  items:
                    type: array
                    items:
                      type: object
                    minItems: 2
                    maxItems: 2
      responses:
        '200':
          description: The project members.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectMember'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    put:
      operationId: putProjectsProjectIdProjectMembers
      summary: Update project member list
      description: >
        Updates the project member list and membership level of users.


        If you leave off a user who's already a member, the user's relationship
        to that project isn't changed.


        If a specified user is already a member, the user's membership is
        changed to the specified level.


        If a specified user is not already a member, the user is added with the
        specified level.
      tags:
        - project_members
      requestBody:
        description: >
          An object that has a `relationships` field, which is an array of
          `[user_id, membership_level]` tuples.


          For example, `{"relationships": [[1234, "editor"], [4567,
          "viewer"]]}` 
        content:
          application/json:
            schema:
              type: object
              properties:
                relationships:
                  description: An array of user ID and membership level pairs (tuples).
                  type: array
                  items:
                    type: array
                    items:
                      type: object
                    minItems: 2
                    maxItems: 2
      responses:
        '200':
          description: The members of the matching project.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectMember'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    delete:
      operationId: deleteProjectsProjectIdProjectMember
      summary: Delete member from project
      description: |
        Removes the specified user(s) from project membership.

        For example, `{"user_ids": [1234,4567]}` 
      tags:
        - project_members
      requestBody:
        description: |
          An object that has a `user_ids`` field, which is an array of user IDs.

          For example, `{"user_ids": [1234,4567]}` 
        content:
          application/json:
            schema:
              type: object
              properties:
                user_ids:
                  description: An array of user IDs.
                  type: array
                  items:
                    type: integer
                    format: int64
                    minimum: 1
                    example: 1234567
                    description: user ID.
      responses:
        '200':
          description: |
            An empty object.
          content:
            application/json:
              schema:
                type: object
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /projects/{project_id}/phases:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: project_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier of the parent project instance.
        example: 1234567
    get:
      summary: List phases
      operationId: getPhases
      tags:
        - phases
      description: Lists the accessible project phases.
      parameters:
        - in: query
          name: from
          schema:
            type: string
            format: date
          description: |
            Get projects that end on or after this date.
        - in: query
          name: to
          schema:
            type: string
            format: date
          description: |
            Get projects that start on or before this date.
        - in: query
          name: strict
          schema:
            type: boolean
          description: >
            Set to `true` to restrict the projects to only those contained
            entirely within the `from` and `to` params.
          example: true
        - in: query
          name: fields
          schema:
            type: string
          description: >
            A comma-separated list (no spaces) of additional fields to include
            with each project in the response. Here are the optional values:
            "tags", "budget_items", "project_state" , "summary",
            "custom_field_values"
          example: >-
            tags,custom_field_values,budget_items,project_state,summary,custom_field_values
        - in: query
          name: filter_field
          schema:
            type: string
            enum:
              - project_state
          description: >
            Specifies the property to filter on. "project_state" is the only
            supported value.
          example: project_state
        - in: query
          name: filter_list
          schema:
            type: string
          description: >
            The value of "filter_field" to match, outputs will be projects with
            state matching this value. Possible values: Internal, Tentative,
            Confirmed
        - in: query
          name: sort_field
          description: |
            A project field on which to sort the projects in the response. 
          schema:
            type: string
            enum:
              - created
              - updated
          example: created
        - in: query
          name: sort_order
          description: The order for sorting the results based on the `sort_field`.
          schema:
            type: string
            enum:
              - ascending
              - descending
          example: ascending
        - in: query
          name: project_code
          schema:
            type: string
          description: |
            Project code to match exactly.
        - in: query
          name: phase_name
          schema:
            type: string
          description: |
            Phase name to match exactly.
        - in: query
          name: with_archived
          description: If set to `true`, includes archived projects.
          schema:
            type: boolean
          example: true
        - in: query
          name: archived
          schema:
            type: boolean
          description: |
            Set to `true`` to include archived projects.
          example: false
        - in: query
          name: per_page
          schema:
            $ref: '#/components/schemas/perPage'
        - in: query
          name: page
          schema:
            $ref: '#/components/schemas/page'
      responses:
        '200':
          description: |
            The accessible phases.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    post:
      operationId: postPhases
      summary: Create phase
      description: >
        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.
      tags:
        - phases
      requestBody:
        description: The property values to apply to a new project phase.
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Phase'
                - type: object
                  properties:
                    name:
                      type: string
                  required:
                    - phase_name
      responses:
        '200':
          description: |
            The new project phase.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhaseCoreAttributesResponse'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /projects/{project_id}/phases/{phase_id}:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: project_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier of the parent project instance.
        example: 1234567
      - in: path
        name: phase_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier of the phase instance.
        example: 45678901
    put:
      summary: Update phase
      operationId: putPhasesId
      tags:
        - phases
      description: >
        Updates the matching 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.
      requestBody:
        description: The property values to apply to the matching phase.
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Phase'
                - type: object
                  properties:
                    archived:
                      type: boolean
                      description: >
                        Set to `true` to archive the phase; set to `false` to
                        unarchive the phase.


                        **Important:** The archived property must be the only
                        request body property.
                      example: true
                    use_parent_bill_rates:
                      type: boolean
                      description: >
                        Set `use_parent_bill_rates` to `true` to use the parent
                        project's bill rates; set it to `false` to use
                        phase-specific bill rates.  
                      example: true
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Phase'
      responses:
        '200':
          description: |
            The updated phase.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhaseCoreAttributesResponse'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    delete:
      summary: Delete phase
      operationId: deletePhasesId
      tags:
        - phases
      description: |
        Removes the matchig phase. 

        > **Note:** A phase can only be deleted if it has no assignments. 
      responses:
        '200':
          description: |
            Removed the matching phase successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    default: true
                  message:
                    type: string
                    enum:
                      - Archived
                    default: Archived
        '404':
          description: |
            Phase not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    default: false
                  message:
                    type: string
                    enum:
                      - not found
                    default: not found
        default:
          description: Generic error payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorPayload'
  /projects/{project_id}/placeholder_resources:
    get:
      summary: List project placeholder resources
      operationId: ListProjectPlaceholderResources
      description: >
        Retrieves a list of placeholder resources assigned to a specific
        project. This is similar to listing [users on a
        project](/api/resource_management/openapi/users-per-project).
      tags:
        - placeholder resources
      parameters:
        - in: path
          name: project_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the project.
      responses:
        '200':
          description: A paginated list of placeholder resources assigned to the project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceholderResourcesResponse'
              example:
                paging:
                  per_page: 20
                  page: 1
                  previous: null
                  self: >-
                    /api/v1/projects/6929276/placeholder_resources?project_id=6929276&page=1
                  next: null
                data: []
        '404':
          description: >-
            The project resource can't be found. The value is invalid or
            missing.
          content:
            text/plain:
              schema:
                type: string
                example: Not Found
                description: >-
                  Returns if the path parameter `project_id` is completely
                  malformed or missing. For example, an empty string.
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
                    description: >-
                      Returns when the `project_id` doesn't exist or is
                      intentionally missing.
  /projects/{project_id}/tags:
    get:
      summary: List project tags
      operationId: getProjectTags
      tags:
        - tags per project
      description: Retrieves a paginated list of all tags attached to a specific project.
      parameters:
        - in: path
          name: project_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the project.
      responses:
        '200':
          description: A list of tags attached to the project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectTagsResponse'
              example:
                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
        '404':
          description: The project ID was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
    post:
      summary: Create and attach a tag to a project
      operationId: postTag
      tags:
        - tags per project
      description: >
        Attaching a tag to a project is technically a “find-or-create”
        operation. If you post a tag with information that doesn't exist for
        your organization, it'll be created and attached to the project
        specified. If the tag already exists, it'll just be attached.


        > **Note:** If you try to create the same tag multiple times, it'll just
        be attached once.
      parameters:
        - in: path
          name: project_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the project.
      requestBody:
        description: The tag value to be created and attached to the project.
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                value:
                  type: string
                  description: The value of the tag to be created or attached.
                  example: Awesome
      responses:
        '200':
          description: The tag was successfully created and/or attached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
              example:
                id: 31
                value: Awesome
        '400':
          description: The request body is invalid or has a missing parameter.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: bad data
                  errors:
                    type: array
                    items:
                      type: string
                    example:
                      - Value can't be blank
                      - Value is too short (minimum is 1 character)
        '404':
          description: The project ID was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
  /projects/{project_id}/tags/{tag_id}:
    delete:
      summary: Disconnect a tag from a project
      operationId: deleteProjectTag
      tags:
        - tags per project
      description: >
        You can remove a tag from a project without deleting it from your
        account settings by using the `/api/v1/projects` endpoint.
      parameters:
        - in: path
          name: project_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the project.
        - in: path
          name: tag_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the tag to disconnect from the project.
      responses:
        '200':
          description: The tag was successfully disconnected from the project.
          content:
            application/json:
              schema:
                type: object
        '404':
          description: The project or tag was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
  /projects/{project_id}/time_entry_categories:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: project_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
    get:
      summary: List project time entry categories
      operationId: getProjectTimeEntryCategories
      tags:
        - budget_item_categories
      description: >-
        Lists the accessible project/phase-specific time entry budget item
        categories.
      parameters:
        - in: query
          name: item_type
          schema:
            $ref: '#/components/schemas/BudgetItemCategory'
          required: true
      responses:
        '200':
          description: >
            The accessible project/phase-specific time entry budget item
            categories.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BudgetItemCategory'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /projects/{project_id}/time_entries:
    get:
      summary: List project time entries
      operationId: ListProjectTimeEntries
      description: Retrieves a paginated list of time entries for a specific project.
      tags:
        - time entries
      parameters:
        - in: path
          name: project_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the project.
        - in: query
          name: from
          schema:
            type: string
            format: date
          description: Get time entries that start on or after this date.
          example: '2017-03-14'
        - in: query
          name: to
          schema:
            type: string
            format: date
          description: Get time entries that end on or before this date.
          example: '2017-03-21'
        - in: query
          name: with_suggestions
          schema:
            type: boolean
            default: false
          description: If set to `true`, includes suggested (unconfirmed) time entries.
        - in: query
          name: sort_field
          schema:
            type: string
            enum:
              - created
              - updated
          description: Field to sort the return document.
        - in: query
          name: sort_order
          schema:
            type: string
            enum:
              - ascending
              - descending
          description: Order to sort the results on.
      responses:
        '200':
          description: A paginated list of time entries for the project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeEntriesResponse'
              examples:
                ProjectHasNoTimeEntries:
                  summary: Project has no time entries
                  value:
                    paging:
                      per_page: 20
                      page: 1
                      previous: null
                      self: >-
                        /api/v1/projects/6261785/time_entries?assignable_id=6261785&page=1
                      next: null
                    data: []
                ProjectHasTimeEntries:
                  summary: Project has time entries
                  value:
                    paging:
                      per_page: 20
                      page: 1
                      previous: null
                      self: >-
                        /api/v1/projects/6261785/time_entries?assignable_id=6261785&page=1
                      next: null
                    data:
                      - id: 3246967835
                        assignable_id: 6261785
                        assignable_type: LeaveType
                        user_id: 1545462
                        bill_rate: null
                        bill_rate_id: null
                        date: '2022-05-12'
                        hours: 8
                        scheduled_hours: null
                        notes: null
                        task: null
                        is_suggestion: false
                        created_at: '2022-04-13T18:01:32Z'
                        updated_at: '2022-04-13T18:01:32Z'
    post:
      summary: Create project time entry
      operationId: CreateProjectTimeEntry
      description: >
        Creates a new time entry for a project. The `assignable_id` in the
        request body is the project ID from the URL, and it must match.


        >**Note:** 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.
      tags:
        - time entries
      parameters:
        - in: path
          name: project_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the project.
      requestBody:
        description: The time entry fields to be created.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeEntryCreateRequest'
            example:
              user_id: 3505944
              assignable_id: 6261785
              date: '2030-01-21'
              hours: 5.5
              notes: Drive to Dallas, TX
              task: Travel
      responses:
        '200':
          description: The time entry was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeEntry'
              example:
                id: 22946312238
                assignable_id: 6261785
                assignable_type: LeaveType
                user_id: 3505944
                bill_rate: null
                bill_rate_id: null
                date: '2030-01-21'
                hours: 5.5
                scheduled_hours: null
                notes: Drive to Dallas, TX
                task: Travel
                is_suggestion: false
                created_at: '2025-09-11T19:32:45Z'
                updated_at: '2025-09-11T19:32:45Z'
        '404':
          description: >-
            The time entry couldn't be created. Invalid input or missing
            parameters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
  /projects/{project_id}/time_entries/{id}:
    get:
      summary: Fetch project time entry
      operationId: FetchProjectTimeEntry
      description: Retrieves a single time entry for a project by its ID.
      tags:
        - time entries
      parameters:
        - in: path
          name: project_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the project.
        - in: path
          name: id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the time entry.
      responses:
        '200':
          description: A paginated list of time entries for the project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeEntry'
              example:
                id: 22945520822
                assignable_id: 6261785
                assignable_type: LeaveType
                user_id: 3505944
                bill_rate: null
                bill_rate_id: null
                date: '2012-01-21'
                hours: 0.5
                scheduled_hours: null
                notes: Drive to Seattle, WA
                task: Travel
                is_suggestion: false
                created_at: '2025-09-11T18:58:51Z'
                updated_at: '2025-09-11T18:58:51Z'
        '404':
          description: >-
            The time entry ID was not found. Invalid input or missing
            parameters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
  /projects/{project_id}/users:
    get:
      summary: List project users
      operationId: getUsersPerProject
      description: |
        Retrieves a list of users associated with a specific project.

        >**Note:** Users are associated with a project via Assignments. 
      tags:
        - users per project
      parameters:
        - in: path
          name: project_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the project.
        - in: query
          name: per_page
          schema:
            type: integer
            default: 20
            maximum: 1000
          description: Parameters for pagination.
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: Parameters for pagination.
        - in: query
          name: fields
          schema:
            type: string
            enum:
              - tags
              - assignments
              - availabilities
              - custom_field_values
          description: >-
            A comma-separated list of additional fields to include in the
            response.
        - in: query
          name: sort_field
          schema:
            type: string
            enum:
              - created
              - updated
              - first_name
              - last_name
              - hire_date
              - termination_date
          description: Field to sort the return document.
        - in: query
          name: sort_order
          schema:
            type: string
            enum:
              - ascending
              - descending
          description: Order to sort the results on.
        - in: query
          name: with_phases
          schema:
            type: boolean
            default: false
          description: >-
            If set to `true`, includes users who are assigned to phases (child
            projects).
        - in: query
          name: with_archived
          schema:
            type: boolean
            default: false
          description: If set to `true`, includes archived users.
        - in: query
          name: include_placeholders
          schema:
            type: boolean
            default: false
          description: If set to `true`, includes placeholder users.
      responses:
        '200':
          description: A paginated list of users for the project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersProjectResponse'
              example:
                paging:
                  per_page: 20
                  page: 1
                  previous: null
                  self: /api/v1/projects/6322282/users?project_id=6322282&page=1
                  next: null
                  count: null
                data:
                  - last_login_time: '2024-02-13T19:59:56Z'
                    billrate: -1
                    id: 1545460
                    first_name: Jane
                    last_name: Doe
                    account_owner: false
                    archived: false
                    billability_target: 80
                    billable: true
                    created_at: '2022-03-23T16:14:01Z'
                    discipline: Learning & Content
                    display_name: Jane Doe
                    email: jane.doe@company.com
                    employee_number: ''
                    guid: d320eb0f-4532-4ec2-a788-934d6907fe5e
                    hire_date: '2021-07-09T00:00:00Z'
                    invitation_pending: false
                    license_type: licensed
                    location: Field - CA
                    location_id: null
                    mobile_phone: ''
                    office_phone: ''
                    role: Onboarding Coordinator
                    termination_date: null
                    type: User
                    updated_at: '2025-08-20T12:07:04Z'
                    user_type_id: 1
                    thumbnail: >-
                      https://aws.smartsheet.com/storageProxy/image/images/u!1!pbHn6QudtPM!xJPkcSvZ7fM!PxN1pNZZK_N
                    has_login: true
                    login_type: smar
                    archived_at: null
        '404':
          description: The project ID was not found or is missing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
  /relationships/project_members:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
    get:
      summary: List members for multiple projects
      operationId: getRelationshipsProjectMembers
      tags:
        - project_members
      description: >
        Lists members for one or more projects.


        To filter on project membership level, set the `membership` query
        parameter to that level. See the `membership` query parameter for
        details.
      parameters:
        - in: query
          name: per_page
          schema:
            $ref: '#/components/schemas/perPage'
        - in: query
          name: page
          schema:
            $ref: '#/components/schemas/page'
        - in: query
          name: membership
          schema:
            type: string
            enum:
              - member
              - viewer
              - reporter
              - scheduler
              - editor
            default: member
          example: member
          description: A membership level on which to filter members.
      responses:
        '200':
          description: The members of the matching projects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectMember'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /relationships/project_memberships:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
    get:
      summary: List project memberships for multiple users
      operationId: getRelationshipsProjectMemberships
      tags:
        - project_memberships
      description: >-
        Lists project memberships for one or more users, optionally at a
        specific membership level.
      parameters:
        - in: query
          name: user_ids
          schema:
            type: string
          example: 1234567,8901234
          description: >-
            A comma-separated list of IDs of users for which to list
            memberships.
        - in: query
          name: membership
          description: Filters on memberships of a particular level.
          schema:
            type: string
            enum:
              - member
              - viewer
              - reporter
              - scheduler
              - editor
            default: member
          example: member
        - in: query
          name: per_page
          schema:
            $ref: '#/components/schemas/perPage'
        - in: query
          name: page
          schema:
            $ref: '#/components/schemas/page'
      responses:
        '200':
          description: |
            The project membership relationships. 
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectMembership'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorPayload'
  /reports/rows:
    post:
      summary: Create rows
      operationId: CreateRows
      description: >
        Generates and returns the detailed rows of a report based on the
        provided parameters. The response is a JSON representation of the report
        rows as seen in the reports UI.
      tags:
        - reports
      requestBody:
        description: >-
          Parameters defining the report's view, time frame, grouping, and
          filtering logic.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportRequestParams'
            example:
              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
      responses:
        '200':
          description: A JSON representation of the report rows.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportRowsResponse'
              example:
                params:
                  view: time_fees_hours
                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
        '400':
          description: >-
            Invalid parameters in the request body (e.g., malformed dates,
            invalid view).
  /reports/totals:
    post:
      summary: Create totals
      operationId: CreateTotals
      description: |
        Generates and returns only the aggregated totals for a report.
      tags:
        - reports
      requestBody:
        description: >-
          Parameters defining the report's view, time frame, grouping, and
          filtering logic.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportRequestParams'
            example:
              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
      responses:
        '200':
          description: A JSON representation of the report totals (aggregated metrics).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportTotalsResponse'
        '400':
          description: Invalid parameters in the request body.
  /roles:
    get:
      summary: List roles
      operationId: ListRoles
      description: Retrieves a paginated list of all accessible roles.
      tags:
        - roles
      parameters:
        - in: query
          name: filter
          schema:
            type: string
          description: >-
            Respects standard filtering parameters (check documentation for
            supported fields).
        - in: query
          name: per_page
          schema:
            type: integer
            default: 20
            maximum: 1000
          description: Parameters for pagination.
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: Parameters for pagination.
      responses:
        '200':
          description: A paginated list of role objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RolesResponse'
              example:
                paging:
                  per_page: 20
                  page: 1
                  previous: null
                  self: /api/v1/roles?&page=1
                  next: null
                data:
                  - id: 165478
                    value: Onboarding Coordinator
                  - id: 223546
                    value: Instructional Designer
        '404':
          description: Not found.
  /roles/{role_id}:
    get:
      summary: Fetch role
      operationId: FetchRole
      description: Returns the role with the matching ID.
      tags:
        - roles
      parameters:
        - in: path
          name: role_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the role.
      responses:
        '200':
          description: The matching role object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
              example:
                id: 987654
                value: Onboarding Coordinator
        '404':
          description: The role ID was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
  /status_options:
    get:
      summary: List status options
      operationId: GetStatusOptions
      description: |
        Retrieves a list of all status options.
      tags:
        - status options
      parameters:
        - in: query
          name: with_deleted
          schema:
            type: boolean
          description: If set to `true`, includes status options that have been deleted.
          example: true
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: The page number to retrieve.
        - in: query
          name: per_page
          schema:
            type: integer
            default: 20
          description: The number of items to return per page.
      responses:
        '200':
          description: A paginated list of status options.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusOptionsResponse'
              example:
                paging:
                  per_page: 20
                  page: 1
                  previous: null
                  self: /api/v1/status_options?with_deleted=true&page=1
                  next: null
                data:
                  - id: 384661
                    label: Scheduled
                    color: blue_bright
                    stage: planned
                    order: 10
                    created_at: '2022-03-22T18:56:10Z'
                    updated_at: '2022-03-22T18:56:10Z'
                    deleted_at: null
                  - id: 384662
                    label: Tentative
                    color: gray
                    stage: planned
                    order: 20
                    created_at: '2022-03-22T18:56:10Z'
                    updated_at: '2022-03-22T18:56:10Z'
                    deleted_at: null
                  - id: 384663
                    label: Blocked
                    color: red
                    stage: in_progress
                    order: 30
                    created_at: '2022-03-22T18:56:10Z'
                    updated_at: '2022-03-22T18:56:10Z'
                    deleted_at: null
  /status_options/{status_option_id}:
    get:
      summary: Fetch status option
      operationId: FetchStatusOption
      description: Retrieves a single status option by its ID.
      tags:
        - status options
      parameters:
        - in: path
          name: status_option_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the status option.
      responses:
        '200':
          description: The requested status option object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusOption'
              example:
                id: 401381
                label: Content Review
                color: orange
                stage: in_progress
                order: 70
                created_at: '2022-05-18T17:11:57Z'
                updated_at: '2022-05-18T17:12:10Z'
                deleted_at: null
        '404':
          description: The status option was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
  /time_entry_categories:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
    get:
      summary: List time entry categories
      operationId: getTimeBudgetItemCategories
      tags:
        - budget_item_categories
      description: |
        Lists the accessible, account-level time budget item categories. 

        > **Note:** Project-specific categories aren't included.
      parameters:
        - in: query
          name: per_page
          schema:
            $ref: '#/components/schemas/perPage'
        - in: query
          name: page
          schema:
            $ref: '#/components/schemas/page'
      responses:
        '200':
          description: |
            The accessible, account-level time budget item categories.

            > **Note:** Project-specific categories aren't included.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BudgetItemCategory'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /time_entries:
    get:
      summary: List time entries
      operationId: ListTimeEntries
      description: Retrieves a paginated list of all time entries in the account.
      tags:
        - time entries
      parameters:
        - in: query
          name: from
          schema:
            type: string
            format: date
          description: Get time entries that start on or after this date.
          example: '2017-03-14'
        - in: query
          name: to
          schema:
            type: string
            format: date
          description: Get time entries that end on or before this date.
          example: '2017-03-21'
        - in: query
          name: with_suggestions
          schema:
            type: boolean
            default: false
          description: If set to `true`, includes suggested (unconfirmed) time entries.
        - in: query
          name: sort_field
          schema:
            type: string
            enum:
              - created
              - updated
          description: Field to sort the return document.
        - in: query
          name: sort_order
          schema:
            type: string
            enum:
              - ascending
              - descending
          description: Order to sort the results on.
      responses:
        '200':
          description: A paginated list of time entries.
          content:
            application/jsqon:
              schema:
                $ref: '#/components/schemas/TimeEntriesResponse'
              example:
                paging:
                  per_page: 20
                  page: 1
                  previous: null
                  self: /api/v1/time_entries?&page=1
                  next: /api/v1/time_entries?&page=2
                data:
                  - id: 3309484855
                    assignable_id: 6368132
                    assignable_type: Project
                    user_id: 1545389
                    bill_rate: 1
                    bill_rate_id: 59455902
                    date: '2022-05-09'
                    hours: 1.58
                    scheduled_hours: null
                    notes: null
                    task: null
                    is_suggestion: false
                    created_at: '2022-05-09T18:00:40Z'
                    updated_at: '2022-05-09T19:35:45Z'
                  - id: 3309870001
                    assignable_id: 6368133
                    assignable_type: Project
                    user_id: 1545389
                    bill_rate: 1
                    bill_rate_id: 59455912
                    date: '2022-05-09'
                    hours: 0.31
                    scheduled_hours: null
                    notes: null
                    task: null
                    is_suggestion: false
                    created_at: '2022-05-09T19:44:23Z'
                    updated_at: '2022-05-09T19:55:37Z'
  /time_entries/{id}:
    get:
      summary: Fetch time entry
      operationId: FetchTimeEntry
      description: Retrieves a single time entry by its ID.
      tags:
        - time entries
      parameters:
        - in: path
          name: id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the time entry.
      responses:
        '200':
          description: The requested time entry object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeEntry'
              example:
                id: 3309484855
                assignable_id: 6368132
                assignable_type: Project
                user_id: 1545389
                bill_rate: 1
                bill_rate_id: 59455902
                date: '2022-05-09'
                hours: 1.58
                scheduled_hours: null
                notes: null
                task: null
                is_suggestion: false
                created_at: '2022-05-09T18:00:40Z'
                updated_at: '2022-05-09T19:35:45Z'
        '404':
          description: >-
            Bad request. The time entry was not found. Invalid input or missing
            parameters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
  /users:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
    get:
      summary: List users
      operationId: getUsers
      tags:
        - users
      description: Lists the accessible account users.
      parameters:
        - in: query
          name: fields
          schema:
            type: string
          description: >
            A comma-separated list (no spaces) of additional fields to include
            for each user in the response. Here are the optional values: "tags",
            "assignments", "availabilities", "custom_field_values", "approvers"
          example: tags,assignments
        - in: query
          name: sort_field
          description: |
            A user field on which to sort the users in the response. 
          schema:
            type: string
            enum:
              - created
              - updated
              - first_name
              - last_name
              - hire_date
              - termination_date
          example: last_name
        - in: query
          name: sort_order
          description: The order for sorting the results based on the `sort_field`.
          schema:
            type: string
            enum:
              - ascending
              - descending
          example: ascending
        - in: query
          name: with_archived
          description: If set to `true`, includes archived users.
          schema:
            type: boolean
          example: true
        - in: query
          name: include_placeholders
          description: If set to `true`, includes placeholder users.
          schema:
            type: boolean
          example: true
        - in: query
          name: include_count
          description: If set to `true`, includes the item count in the paging metadata.
          schema:
            type: boolean
          example: true
        - in: query
          name: per_page
          schema:
            $ref: '#/components/schemas/perPage'
        - in: query
          name: page
          schema:
            $ref: '#/components/schemas/page'
      responses:
        '200':
          description: |
            The account users. 
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorPayload'
    post:
      summary: Create user
      operationId: postUsers
      tags:
        - users
      description: |
        Creates a user.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/User'
              required:
                - first_name
                - last_name
                - email
                - user_type_id
                - archived
      responses:
        '200':
          description: |
            The new user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        default:
          description: Generic error payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorPayload'
  /users/{user_id}:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: user_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
    get:
      summary: Fetch user
      operationId: getUsersId
      tags:
        - users
      description: |
        Returns the matching user.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: |
            User not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    default: false
                  message:
                    type: string
                    enum:
                      - not found
                    default: not found
        default:
          description: Generic error payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorPayload'
    put:
      summary: Update user
      operationId: putUsersId
      description: |
        Updates the matching user. 
      tags:
        - users
      requestBody:
        description: >
          An object containing the key/value pairs of attributes to update with
          the new values.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        default:
          description: Generic error payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorPayload'
    delete:
      summary: Delete user
      operationId: deleteUsersId
      tags:
        - users
      description: |
        Remove the matchig user.  
      responses:
        '200':
          description: |
            Removed the matching user successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    default: true
                  message:
                    type: string
                    enum:
                      - Archived
                    default: Archived
        '404':
          description: |
            User not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    default: false
                  message:
                    type: string
                    enum:
                      - not found
                    default: not found
        default:
          description: Generic error payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorPayload'
  /users/{user_id}/assignments:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: user_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
    get:
      summary: List user assignments
      operationId: getUsersUserIdAssignments
      tags:
        - assignments_per_user
      description: |
        Returns the assignments for the matching user.
      parameters:
        - in: query
          name: per_page
          schema:
            $ref: '#/components/schemas/perPage'
        - in: query
          name: page
          schema:
            $ref: '#/components/schemas/page'
        - in: query
          name: from
          schema:
            type: string
            format: date
          description: Filter on assignments that end on or after this date.
        - in: query
          name: to
          schema:
            type: string
            format: date
          description: Filter on assignments that start on or before this date.
        - in: query
          name: with_phases
          schema:
            type: boolean
            default: false
          description: If `true`, include assignments to phases. Otherwise, exclude them.
      responses:
        '200':
          description: The assignments for the matching user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Assignment'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    post:
      operationId: postUsersUserIdAssignments
      summary: Create user assignment
      description: >
        Creates a user assignment.


        Typical parameters:


        - `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`)
      tags:
        - assignments_per_user
      requestBody:
        description: The property values to apply to a new user assignment.
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Assignment'
                - type: object
                  required:
                    - assignable_id
                  properties:
                    assignable_id:
                      type: integer
                      format: int64
                      minimum: 1
                      example: 1234
                      description: >-
                        The ID of the project, phase, or leave type to which the
                        the assignment applies.
      responses:
        '200':
          description: |
            The new user assignment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assignment'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /users/{user_id}/assignments/{assignment_id}:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: user_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
      - in: path
        name: assignment_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 889
    get:
      summary: Fetch user assignment
      operationId: getUsersUserIdAssignmentsAssignmentsId
      tags:
        - assignments_per_user
      description: |
        Returns the matching user assignment.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assignment'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    put:
      operationId: putUsersUserIdAssignmentsAssignmentId
      summary: Update user assignment
      description: >
        Updates the matching user assignment.


        Typical parameters:


        - `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`
      tags:
        - assignments_per_user
      requestBody:
        description: The property values to apply to the user assignment.
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Assignment'
      responses:
        '200':
          description: |
            The updated user assignment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assignment'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    delete:
      operationId: deletetUsersUserIdAssignmentsAssignmentId
      summary: Delete user assignment
      description: |
        Deletes the matching user assignment.
      tags:
        - assignments_per_user
      responses:
        '200':
          description: |
            An empty object.
          content:
            application/json:
              schema:
                type: object
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /users/{user_id}/availabilities:
    get:
      summary: List availabilities
      operationId: getAvailabilityById
      description: >-
        Retrieves a paginated list of availability time blocks for a specific
        user.
      tags:
        - availabilities
      parameters:
        - in: path
          name: user_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the user.
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: The page number to retrieve.
        - in: query
          name: per_page
          schema:
            type: integer
            default: 20
          description: The number of items to return per page.
      responses:
        '200':
          description: A paginated list of availability blocks for the user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailabilitiesResponse'
              example:
                paging:
                  per_page: 20
                  page: 1
                  previous: null
                  self: /api/v1/users/3505944/availabilities?user_id=3505944&page=1
                  next: null
                data:
                  - id: 52
                    user_id: 269
                    day0: 0
                    day1: 8
                    day2: 8
                    day3: 4
                    day4: 8
                    day5: 8
                    day6: 0
                    starts_at: '2017-01-30'
                    ends_at: '2017-07-28'
                    created_at: '2013-05-08T00:01:34Z'
                    updated_at: '2025-08-27T22:44:23Z'
        '404':
          description: The user ID was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
    post:
      summary: Create availability
      operationId: createAvailability
      description: >
        Creates a new availability time block for a user.


        > **Note:** In the current version of the API, updating part-time
        availabilities will **NOT** automatically update existing assignments
        and their suggested time entries to match.
      tags:
        - availabilities
      parameters:
        - in: path
          name: user_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the user.
      requestBody:
        description: The availability block to be created.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AvailabilityCreateRequest'
            example:
              starts_at: '2017-01-30'
              ends_at: '2017-07-28'
              day0: 0
              day1: 8
              day2: 8
              day3: 4
              day4: 8
              day5: 8
              day6: 0
      responses:
        '201':
          description: The availability block was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Availability'
              example:
                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
                created_at: '2013-05-08T00:01:34Z'
                updated_at: '2013-05-08T00:01:34Z'
        '404':
          description: The user ID was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
  /users/{user_id}/availabilities/{id}:
    get:
      summary: Fetch availability
      operationId: fetchAvailability
      description: Retrieves a single availability time block by its ID.
      tags:
        - availabilities
      parameters:
        - in: path
          name: user_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the user.
        - in: path
          name: id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the availability block.
      responses:
        '200':
          description: The requested availability block.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Availability'
              example:
                id: 52
                user_id: 269
                day0: 0
                day1: 8
                day2: 8
                day3: 4
                day4: 8
                day5: 8
                day6: 0
                starts_at: '2017-01-30'
                ends_at: '2017-07-28'
                created_at: '2013-05-08T00:01:34Z'
                updated_at: '2025-08-27T22:44:23Z'
        '404':
          description: The availability block was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
    put:
      summary: Update availability
      operationId: updateAvailability
      description: Updates an existing availability block for a user.
      tags:
        - availabilities
      parameters:
        - in: path
          name: user_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the user.
        - in: path
          name: id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the availability block.
      requestBody:
        description: The availability block fields to be updated.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AvailabilityCreateRequest'
            example:
              starts_at: '2017-01-30'
              ends_at: '2017-07-28'
              day0: 0
              day1: 8
              day2: 8
              day3: 4
              day4: 8
              day5: 8
              day6: 0
      responses:
        '200':
          description: The availability block was updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Availability'
              example:
                id: 52
                user_id: 269
                day0: 0
                day1: 8
                day2: 8
                day3: 4
                day4: 8
                day5: 8
                day6: 0
                starts_at: '2017-01-30'
                ends_at: '2017-07-28'
                created_at: '2013-05-08T00:01:34Z'
                updated_at: '2025-08-27T12:00:00Z'
        '404':
          description: The availability block was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
    delete:
      summary: Delete availability
      operationId: deleteAvailability
      description: Deletes an availability block from a user's profile.
      tags:
        - availabilities
      parameters:
        - in: path
          name: user_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the user.
        - in: path
          name: id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the availability block.
      responses:
        '200':
          description: The availability block was deleted successfully.
          content:
            application/json:
              schema:
                type: object
        '404':
          description: The availability block was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
  /users/{user_id}/expense_items:
    get:
      summary: List user expense items
      operationId: ListUserExpenseItems
      description: Retrieves a list of expense items reported by a specific user.
      tags:
        - expense items
      parameters:
        - in: path
          name: user_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the user.
        - in: query
          name: from
          schema:
            type: string
            format: date
          description: Get expenses reported on or after this date.
          example: '2017-03-14'
        - in: query
          name: to
          schema:
            type: string
            format: date
          description: Get expenses reported on or before this date.
          example: '2017-03-21'
        - in: query
          name: per_page
          schema:
            type: integer
            default: 20
            maximum: 1000
          description: Parameters for pagination.
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: Parameters for pagination.
      responses:
        '200':
          description: A list of expense items for a user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpenseItemsResponse'
              example:
                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
                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'
        '404':
          description: The user ID was not found.
    post:
      summary: Create expense item
      operationId: CreateExpenseItem
      description: |
        Creates a new expense item for a user.
      tags:
        - expense items
      parameters:
        - in: path
          name: user_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the user.
      requestBody:
        description: The expense item fields to be created.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExpenseItemCreateRequest'
            example:
              date: '2015-04-09'
              amount: 10
              user_id: 123456
              project_id: 321234
      responses:
        '201':
          description: The expense item was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpenseItem'
              example:
                id: 98765
                assignable_id: 12345
                assignable_type: Project
                user_id: 990011
                amount: 500
                date: '2025-04-09'
                category: null
                notes: null
                created_at: '2025-09-25T03:13:12Z'
                updated_at: '2025-09-25T03:13:12Z'
        '404':
          description: The user ID was not found.
  /users/{user_id}/expense_items/{expense_item_id}:
    get:
      summary: Fetch user expense item
      operationId: FetchUserExpenseItem
      description: Retrieves a single expense item by its ID.
      tags:
        - expense items
      parameters:
        - in: path
          name: user_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the user.
        - in: path
          name: expense_item_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the expense item.
      responses:
        '200':
          description: The requested expense item object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpenseItem'
              example:
                id: 517417
                assignable_id: 6929276
                assignable_type: Project
                user_id: 654321
                amount: 500
                date: '2025-04-09'
                category: null
                notes: null
                created_at: '2025-09-25T03:12:51Z'
                updated_at: '2025-09-25T03:12:51Z'
        '404':
          description: The expense item was not found.
    put:
      summary: Update expense item
      operationId: UpdateExpenseItem
      description: Updates an existing expense item.
      tags:
        - expense items
      parameters:
        - in: path
          name: user_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the user.
        - in: path
          name: expense_item_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the expense item.
      requestBody:
        description: The expense item fields to be updated.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExpenseItemUpdateRequest'
            example:
              date: '2025-04-09'
              amount: 150
      responses:
        '200':
          description: The expense item was updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpenseItem'
              example:
                id: 517419
                assignable_id: 6929276
                assignable_type: Project
                user_id: 654987
                amount: 555
                date: '2055-04-09'
                category: null
                notes: null
                created_at: '2025-09-25T03:23:46Z'
                updated_at: '2025-09-25T17:28:16Z'
        '404':
          description: The expense item was not found.
    delete:
      summary: Delete expense item
      operationId: DeleteExpenseItem
      description: Deletes an expense item by its ID.
      tags:
        - expense items
      parameters:
        - in: path
          name: user_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the user.
        - in: path
          name: expense_item_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the expense item.
      responses:
        '200':
          description: The expense item was deleted successfully.
          content:
            application/json:
              schema:
                type: object
        '404':
          description: The expense item was not found.
  /users/{user_id}/custom_field_values:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: user_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
    get:
      summary: List user custom field values
      operationId: getUsersUserIdCustomFieldValues
      tags:
        - custom_field_values_per_user
      description: |
        Returns the custom field values for the matching user.
      parameters:
        - in: query
          name: per_page
          schema:
            $ref: '#/components/schemas/perPage'
        - in: query
          name: page
          schema:
            $ref: '#/components/schemas/page'
      responses:
        '200':
          description: The custom field values for the matching user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomFieldValue'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    post:
      operationId: postUsersUserIdCustomFieldValues
      summary: Create user custom field value
      description: |
        Creates a user custom field value.
      tags:
        - custom_field_values_per_user
      requestBody:
        description: The property values to apply to a new user custom field value.
        content:
          application/json:
            schema:
              type: object
              required:
                - custom_field_id
                - value
              properties:
                custom_field_id:
                  type: integer
                  format: int64
                  minimum: 1
                  description: The unique identifier of the custom field.
                value:
                  $ref: '#/components/schemas/CustomFieldValueValue'
      responses:
        '200':
          description: |
            The new user custom field value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldValue'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /users/{user_id}/custom_field_values/{custom_field_value_id}:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: user_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
      - in: path
        name: custom_field_value_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 889
    get:
      summary: Fetch user custom field value
      operationId: getUsersUserIdCustomFieldValuesCustomFieldValuesId
      tags:
        - custom_field_values_per_user
      description: |
        Returns the matching user custom field value.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldValue'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    put:
      operationId: putUsersUserIdCustomFieldValuesCustomFieldValueId
      summary: Update user custom field value
      description: |
        Updates the matching user custom field value.
      tags:
        - custom_field_values_per_user
      requestBody:
        description: The property values to apply to the user custom field value.
        content:
          application/json:
            schema:
              type: object
              properties:
                value:
                  $ref: '#/components/schemas/CustomFieldValueValue'
      responses:
        '200':
          description: |
            The updated user custom field value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldValue'
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /users/{user_id}/project_memberships:
    parameters:
      - in: header
        name: Content-Type
        required: true
        schema:
          type: string
          enum:
            - application/json
        example: application/json
      - in: path
        name: user_id
        schema:
          type: integer
          format: int64
          minimum: 1
        required: true
        description: Unique identifier for the resource instance.
        example: 1234567
    get:
      summary: List user project memberships
      operationId: getUsersUserIdProjectMemberships
      tags:
        - project_memberships
      description: >
        Lists project memberships for the matching user.


        To filter on project membership level, set the `membership` query
        parameter to that level. See the `membership` query parameter for
        details.
      parameters:
        - in: query
          name: per_page
          schema:
            $ref: '#/components/schemas/perPage'
        - in: query
          name: page
          schema:
            $ref: '#/components/schemas/page'
        - in: query
          name: from
          schema:
            type: string
            format: date
          description: Filter on project memberships that end on or after this date.
        - in: query
          name: to
          schema:
            type: string
            format: date
          description: Filter on project memberships that start on or before this date.
        - in: query
          name: membership
          schema:
            type: string
            enum:
              - member
              - viewer
              - reporter
              - scheduler
              - editor
            default: member
          example: member
          description: A membership level on which to filter projects.
      responses:
        '200':
          description: The project memberships for the matching user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectMembership'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    post:
      operationId: postUsersUserIdProjectMemberships
      summary: Set user project memberships
      description: >
        Sets the user's membership for all projects, replacing all existing
        memberships.


        > **Warning:** This operation replaces the user's membership list.

        >

        > To add the user to a project, alternatively user the [Update user
        project
        memberships](/api/resource_management/openapi/project_memberships/putusersuseridprojectmemberships)
        operation.


        If you leave off a project to which the user currently belongs, the user
        is **REMOVED** from that project. 


        If the user is already a member of a specified project, the user's
        membership is changed to the specified level.


        If the user is not already a member of a specified project, the user is
        added with the specified level.


        The JSON body should include a `relationships` field with `[project_id,
        membership_level]` tuples.


        For example, `{"relationships": [[1122, "editor"], [3344, "editor"]]}` 
      tags:
        - project_memberships
      requestBody:
        description: >
          For example, `{"relationships": [[1122, "editor"], [3344,
          "editor"]]}` 
        content:
          application/json:
            schema:
              type: object
              properties:
                relationships:
                  description: An array of project ID and membership level pairs (tuples).
                  type: array
                  items:
                    type: array
                    items:
                      type: object
                      minItems: 2
                      maxItems: 2
      responses:
        '200':
          description: The project memberships for the matching user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectMembership'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    put:
      operationId: putUsersUserIdProjectMemberships
      summary: Update user project memberships
      description: >
        Updates the user's membership level for specified projects. 


        If you leave off a project to which the user belongs, the user's
        relationship to that project isn't changed.


        If the user is already a member of a specified project, the user's
        membership is changed to the specified level.


        If the user is not already a member of a specified project, the user is
        added with the specified level.
      tags:
        - project_memberships
      requestBody:
        description: >
          For example, `{"relationships": [[1122, "editor"], [3344,
          "editor"]]}` 
        content:
          application/json:
            schema:
              type: object
              properties:
                relationships:
                  description: An array of project ID and membership level pairs (tuples).
                  type: array
                  items:
                    type: array
                    items:
                      type: object
                    minItems: 2
                    maxItems: 2
      responses:
        '200':
          description: The project memberships for the matching user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paging:
                    $ref: '#/components/schemas/PagingMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectMembership'
                required:
                  - paging
                  - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    delete:
      operationId: deleteUsersUserIdProjectMemberships
      summary: Delete user project memberships
      description: >
        Removes the user's membership to the projects specified.


        In the JSON body, specify a `project_ids` field, set to an array of
        project IDs (for example, `[project_id, project_id, ...]`).
      tags:
        - project_memberships
      requestBody:
        description: >
          A `project_ids` field, which is an array of `[project_id, project_id,
          ...]`.
        content:
          application/json:
            schema:
              type: object
              properties:
                project_ids:
                  description: An array of project IDs.
                  type: array
                  items:
                    type: integer
                    format: int64
                    minimum: 1
                    example: 1122334
                    description: Project ID.
      responses:
        '200':
          description: |
            An empty object.
          content:
            application/json:
              schema:
                type: object
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /users/{user_id}/statuses:
    get:
      summary: Fetch user status
      operationId: getUserStatuses
      description: Retrieves a paginated list of statuses for a specific user.
      tags:
        - user statuses
      parameters:
        - in: path
          name: user_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the user.
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: The page number to retrieve.
        - in: query
          name: per_page
          schema:
            type: integer
            default: 20
          description: The number of items to return per page.
      responses:
        '200':
          description: A list of statuses for the user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserStatusesResponse'
              example:
                paging:
                  per_page: 20
                  page: 1
                  previous: null
                  self: /api/v1/users/3505944/statuses?user_id=3505944&page=1
                  next: null
                data:
                  - id: 1
                    assignable_id: 4
                    user_id: 1
                    current_task: null
                    status: ITO
                    start: null
                    end: null
                    message: Hacking away
                    created_at: '2013-09-12T14:33:05Z'
                    updated_at: '2013-09-12T14:33:05Z'
        '404':
          description: The user ID was not found or is missing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
    post:
      summary: Set user status
      operationId: postUserStatus
      description: Creates a new status for a user.
      tags:
        - user statuses
      parameters:
        - in: path
          name: user_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the user.
      requestBody:
        description: The status information to create or update.
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/StatusCreateRequest'
            example:
              status: OOO
      responses:
        '200':
          description: The status was created or updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
              example:
                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
        '400':
          description: The user status is invalid or missing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: bad data
                  errors:
                    type: array
                    items:
                      type: string
                    example:
                      - Status must be a valid code
        '403':
          description: The user ID was not found or is missing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: forbidden
                  errors:
                    type: array
                    items:
                      type: string
                    example:
                      - access denied
  /users/{user_id}/tags:
    get:
      summary: List user tags
      operationId: getUserTag
      description: |
        Retrieves a paginated list of all tags attached to a specific user.
      tags:
        - tags per user
      parameters:
        - in: path
          name: user_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the user.
      responses:
        '200':
          description: A list of tags attached to the user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserTagsResponse'
              example:
                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
        '404':
          description: The user ID was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
    post:
      summary: Tag user
      operationId: postUserTag
      description: >
        Attaching a tag to a user is technically a "find-or-create" operation.
        If the tag doesn't exist, it'll be created and attached to the user
        specified. If it already exists, it'll only be attached to the user.


        > **Note:** If you try to create the same tag multiple times, it'll just
        be attached once.
      tags:
        - tags per user
      parameters:
        - in: path
          name: user_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the user.
      requestBody:
        description: The tag value to be created and attached to the user.
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                value:
                  type: string
                  description: The value of the tag to be created or attached.
                  example: Awesome
      responses:
        '200':
          description: The tag was successfully created and/or attached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
              example:
                id: 31
                value: Awesome
        '400':
          description: Bad request. The request body is invalid or has a missing parameter.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: bad data
                  errors:
                    type: array
                    items:
                      type: string
                    example:
                      - Value can't be blank
                      - Value is too short (minimum is 1 character)
        '404':
          description: The user ID was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
  /users/{user_id}/tags/{tag_id}:
    delete:
      summary: Untag user
      operationId: deleteUserTag
      description: >
        You can remove a tag from a user without deleting it from your account
        settings by using the `/api/v1/users` endpoint.
      tags:
        - tags per user
      parameters:
        - in: path
          name: user_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the user.
        - in: path
          name: tag_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the tag to disconnect from the user.
      responses:
        '200':
          description: The tag was successfully disconnected from the user.
          content:
            application/json:
              schema:
                type: object
        '404':
          description: The user or tag was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
  /users/{user_id}/time_entries:
    get:
      summary: List user time entries
      operationId: ListUserTimeEntries
      description: Retrieves a paginated list of time entries for a specific user.
      tags:
        - time entries
      parameters:
        - in: path
          name: user_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the user.
        - in: query
          name: from
          schema:
            type: string
            format: date
          description: Get time entries that start on or after this date.
          example: '2017-03-14'
        - in: query
          name: to
          schema:
            type: string
            format: date
          description: Get time entries that end on or before this date.
          example: '2017-03-21'
        - in: query
          name: with_suggestions
          schema:
            type: boolean
            default: false
          description: If set to `true`, includes suggested (unconfirmed) time entries.
        - in: query
          name: sort_field
          schema:
            type: string
            enum:
              - created
              - updated
          description: Field to sort the return document.
        - in: query
          name: sort_order
          schema:
            type: string
            enum:
              - ascending
              - descending
          description: Order to sort the results on.
      responses:
        '200':
          description: A paginated list of time entries for the user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeEntriesResponse'
              examples:
                UserHasNoTimeEntries:
                  summary: User has no time entries
                  value:
                    paging:
                      per_page: 20
                      page: 1
                      previous: null
                      self: >-
                        /api/v1/users/%7Buser_id%7D/time_entries?user_id=%7Buser_id%7D&page=1
                      next: null
                    data: []
                UserHasTimeEntries:
                  summary: User has time entries
                  value:
                    paging:
                      per_page: 20
                      page: 1
                      previous: null
                      self: >-
                        /api/v1/users/3505944/time_entries?user_id=3505944&page=1
                      next: null
                    data:
                      - id: 22945507745
                        assignable_id: 6261785
                        assignable_type: LeaveType
                        user_id: 3505944
                        bill_rate: null
                        bill_rate_id: null
                        date: '2012-01-21'
                        hours: 0.5
                        scheduled_hours: null
                        notes: Drive to Seattle, WA
                        task: Travel
                        is_suggestion: false
                        created_at: '2025-09-11T18:57:40Z'
                        updated_at: '2025-09-11T18:57:40Z'
                      - id: 22945520822
                        assignable_id: 6261785
                        assignable_type: LeaveType
                        user_id: 3505944
                        bill_rate: null
                        bill_rate_id: null
                        date: '2012-01-21'
                        hours: 0.5
                        scheduled_hours: null
                        notes: Drive to Seattle, WA
                        task: Travel
                        is_suggestion: false
                        created_at: '2025-09-11T18:58:51Z'
                        updated_at: '2025-09-11T18:58:51Z'
                      - id: 22945586006
                        assignable_id: 6261785
                        assignable_type: LeaveType
                        user_id: 3505944
                        bill_rate: null
                        bill_rate_id: null
                        date: '2012-01-21'
                        hours: 3
                        scheduled_hours: null
                        notes: Drive to Toronto, ON
                        task: Travel
                        is_suggestion: false
                        created_at: '2025-09-11T19:02:54Z'
                        updated_at: '2025-09-11T19:02:54Z'
    post:
      summary: Create user time entry
      operationId: CreateUserTimeEntry
      description: >
        Creates a new time entry for a user. The `user_id` in the URL must match
        the `user_id` in the request body if it's supplied.


        >**Note:** 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.
      tags:
        - time entries
      parameters:
        - in: path
          name: user_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the user.
      requestBody:
        description: The time entry fields to be created.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeEntryCreateRequest'
      responses:
        '200':
          description: The time entry was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeEntry'
              example:
                id: 22945520822
                assignable_id: 6261785
                assignable_type: LeaveType
                user_id: 3505944
                bill_rate: null
                bill_rate_id: null
                date: '2012-01-21'
                hours: 0.5
                scheduled_hours: null
                notes: Drive to Seattle, WA
                task: Travel
                is_suggestion: false
                created_at: '2025-09-11T18:58:51Z'
                updated_at: '2025-09-11T18:58:51Z'
        '404':
          description: >-
            Bad request. The time couldn't be created. The `user_id` was not
            found. Invalid input or missing parameters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
  /users/{user_id}/time_entries/{id}:
    get:
      summary: Fetch user time entry
      operationId: FetchUserTimeEntry
      description: Retrieves a single time entry for a user by its ID.
      tags:
        - time entries
      parameters:
        - in: path
          name: user_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the user.
        - in: path
          name: id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the time entry.
      responses:
        '200':
          description: The time entry loads successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeEntry'
              example:
                id: 22945618474
                assignable_id: 6261785
                assignable_type: LeaveType
                user_id: 3505944
                bill_rate: null
                bill_rate_id: null
                date: '2012-01-21'
                hours: 5.5
                scheduled_hours: null
                notes: Drive to Seattle, WA
                task: Travel
                is_suggestion: false
                created_at: '2025-09-11T19:04:40Z'
                updated_at: '2025-09-11T19:04:40Z'
        '404':
          description: The time entry was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
    put:
      summary: Update user time entry
      operationId: UpdateUserTimeEntry
      description: Updates an existing time entry.
      tags:
        - time entries
      parameters:
        - in: path
          name: user_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the user.
        - in: path
          name: id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the time entry.
      requestBody:
        description: The time entry fields to be updated.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeEntryCreateRequest'
            example:
              user_id: 3505944
              assignable_id: 6261785
              date: '2025-01-21'
              hours: 7
              notes: Staying home
              task: Sickness
      responses:
        '200':
          description: The time entry was updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeEntry'
              example:
                id: 22945618474
                assignable_id: 6261785
                assignable_type: LeaveType
                user_id: 3505944
                bill_rate: null
                bill_rate_id: null
                date: '2025-01-21'
                hours: 7
                scheduled_hours: null
                notes: Staying home
                task: Sickness
                is_suggestion: false
                created_at: '2025-09-11T19:04:40Z'
                updated_at: '2025-09-11T19:20:57Z'
        '404':
          description: The time entry was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: internal error
    delete:
      summary: Delete user time entry
      operationId: DeleteUserTimeEntry
      description: Deletes an existing time entry.
      tags:
        - time entries
      parameters:
        - in: path
          name: user_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the user.
        - in: path
          name: id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the time entry.
      responses:
        '200':
          description: The time entry was deleted successfully.
          content:
            application/json:
              schema:
                type: object
        '404':
          description: The time entry was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
  /webhooks:
    get:
      summary: List webhooks
      operationId: ListWebhooks
      description: Lists all the webhooks for your organization.
      tags:
        - webhooks
      responses:
        '200':
          description: >-
            Retrieves a paginated list of all webhooks for your organization. If
            no webhooks are found, the response body is blank. You can also get
            a list with deleted options by adding the `with_deleted=true`
            parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhooksResponse'
              example:
                paging:
                  per_page: 20
                  page: 1
                  previous: null
                  self: /api/v1/webhooks?&page=1
                  next: null
                data:
                  - id: 123456
                    url: https://hooks.example.com/process_webhooks
                    status: active
                    event_type: project.created
    post:
      summary: Create webhook
      operationId: CreateWebhook
      description: >
        Creates a webhook that you can use to receive notifications about key
        events. Currently, webhooks are supported for the following events:


        | **Event type** | **Description** |

        | :--- | :--- |

        | `project.created` | Fires when a new project is created |

        | `project.updated` | Fires when a project is updated |

        | `time.entry.created` | Fires when a new time entry is created |

        | `time.entry.updated` | Fires when a time entry is updated |

        | `user.created` | Fires when a new time entry is created |

        | `user.updated` | Fires when a user is updated |

        | `assignment.created` | Fires when a new assignment is created |

        | `assignment.updated` | Fires when an assignment is updated |
      tags:
        - webhooks
      requestBody:
        description: The webhook details to be created.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreateRequest'
            example:
              url: https://hooks.example.com/process_webhooks
              event_type: project.created
      responses:
        '200':
          description: The webhook was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
              example:
                id: 1
                organization_id: 1
                url: https://hooks.example.com/process_webhooks
                status: active
                event_type: project.created
        '403':
          description: The request body is invalid or a duplicate webhook already exists..
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: bad data
                  errors:
                    type: array
                    items:
                      type: string
              examples:
                InvalidURL:
                  summary: Invalid URL
                  value:
                    message: bad data
                    errors:
                      - Url Invalid URL
                DuplicateWebhook:
                  summary: Duplicate Webhook
                  value:
                    message: bad data
                    errors:
                      - Webhook for this event type already exists at this url
                EventTypeBlank:
                  summary: Event Type Cannot Be Blank
                  value:
                    message: bad data
                    errors:
                      - Event type can't be blank
  /webhooks/{webhook_id}:
    get:
      summary: Show single webhook
      operationId: ShowSingleWebhook
      description: Retrieves a single webhook by its ID.
      tags:
        - webhooks
      parameters:
        - in: path
          name: webhook_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the webhook.
      responses:
        '200':
          description: The requested webhook object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
              example:
                id: 123456
                url: https://hooks.example.com/process_webhooks
                status: active
                event_type: project.created
        '404':
          description: The webhook was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
    delete:
      summary: Delete webhook
      operationId: DeleteWebhook
      description: Deletes a webhook.
      tags:
        - webhooks
      parameters:
        - in: path
          name: webhook_id
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          description: The ID of the webhook.
      responses:
        '200':
          description: The webhook was deleted successfully.
          content:
            application/json:
              schema:
                type: object
        '404':
          description: The webhook was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not found
components:
  securitySchemes:
    AuthToken:
      type: apiKey
      in: header
      name: auth
      description: Auth token for authentication.
  schemas:
    APIToken:
      title: API token
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          description: The unique ID of the API token.
          example: 123456
        title:
          type: string
          nullable: true
          description: The title of the token. Can be null.
          example: primary
        token:
          type: string
          description: The token string.
          example: <token_string>
    perPage:
      title: per_page
      type: integer
      format: int32
      maximum: 1000
      description: |
        The maximum number of items to show per response page.
      default: 20
      example: 100
    PagingMetadata:
      title: Paging metadata
      type: object
      properties:
        per_page:
          $ref: '#/components/schemas/perPage'
        page:
          type: integer
          format: int32
          description: |
            The current response page number.
          minimum: 1
          default: 1
          example: 1
        previous:
          type: string
          nullable: true
          description: >
            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
          readOnly: true
        self:
          type: string
          description: |
            The path and query parameters to get the current page of items.
          example: /api/v1/users?per_page=1000&page=2
          readOnly: true
        next:
          type: string
          nullable: true
          description: >
            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
          readOnly: true
        count:
          type: integer
          format: int64
          nullable: true
          description: |
            The total number of items in all the pages.
          minimum: 0
    APITokensResponse:
      title: API tokens response
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/APIToken'
        paging:
          $ref: '#/components/schemas/PagingMetadata'
    page:
      title: page
      type: integer
      format: int32
      description: |
        The response page to return.
      minimum: 1
      default: 1
      example: 2
    Approval:
      title: Approval record
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          description: Unique identifier for the approval record.
          example: 890
        status:
          type: string
          enum:
            - pending
            - approved
            - rejected
          description: The current status of the approval.
          example: pending
        approvable_id:
          type: integer
          description: The ID of the record being approved (TimeEntry or ExpenseItem).
          example: 123
        approvable_type:
          type: string
          enum:
            - TimeEntry
            - ExpenseItem
          description: The type of record being approved.
          example: TimeEntry
        submitted_by:
          type: integer
          description: The ID of the user who submitted the record.
          example: 8
        submitted_at:
          type: string
          format: date-time
          description: The timestamp when the record was submitted for approval.
          example: '2016-10-13T20:16:40Z'
        approved_by:
          type: integer
          nullable: true
          description: >-
            The ID of the user who approved the record, or null if not yet
            approved.
          example: null
        approved_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            The timestamp when the record was approved, or null if not yet
            approved.
          example: null
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
    ApprovalsResponse:
      title: Approvals response
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/PagingMetadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Approval'
    ApprovableObject:
      title: Approvable object
      type: object
      description: The minimal data required to submit or approve a record.
      required:
        - id
        - type
        - updated_at
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          description: The ID of the Time Entry or Expense Item.
          example: 123
        type:
          type: string
          enum:
            - TimeEntry
            - ExpenseItem
          description: The type of resource being submitted.
          example: TimeEntry
        updated_at:
          type: string
          format: date-time
          description: >-
            The current `updated_at` timestamp of the record, required for
            concurrency checks.
          example: '2016-10-04T15:33:32Z'
    ApprovalProcessRequest:
      title: Approval process request
      type: object
      required:
        - approvables
        - status
      properties:
        approvables:
          type: array
          description: An array of records being submitted or approved.
          items:
            $ref: '#/components/schemas/ApprovableObject'
        status:
          type: string
          enum:
            - pending
            - approved
          description: The desired status change.
          example: pending
        updated_at:
          type: string
          format: date-time
          description: >
            The current `updated_at` timestamp of the record, **required for
            concurrency checks**.

            This value must exactly match the timestamp from the latest GET
            response to ensure the record hasn't been modified by another user.
          example: '2016-10-04T15:33:32Z'
    AssignableLeaveType:
      title: Assignable LeaveType
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          description: Unique identifier for the resource instance.
          example: 821065
          readOnly: true
        description:
          type: string
          description: |
            Describes the Assignable.
          example: Big pool in a small backyard.
        guid:
          type: string
          description: |
            Globally Unique Identifier for the resource instance.
          example: d9d0de8f-32cc-4c0b-8af1-648ce039e3f6
          readOnly: true
        name:
          type: string
          description: Assignable name.
          example: 'PR001: Example Project'
        deleted_at:
          type: string
          format: date-time
          description: >
            If set, it's the date and time the Assignable was archived;
            otherwise, the object is active.
          readOnly: true
        created_at:
          type: string
          format: date-time
          description: |
            Assignable creation date.
          example: '2025-01-22T06:00:30Z'
          readOnly: true
        updated_at:
          type: string
          format: date-time
          description: |
            Date of the most recent modification. 
          example: '2025-01-22T06:13:40Z'
          readOnly: true
        type:
          type: string
          enum:
            - LeaveType
            - Project
          description: |
            The object type.
          example: Project
          readOnly: true
        starts_at:
          type: string
          format: date
          description: |
            The Assignable's starting date.
          example: '2025-01-27'
        ends_at:
          type: string
          format: date
          description: |
            The Assignable's ending date.
          example: '2025-05-29'
        project_code:
          type: string
          description: >
            If the Assignable is a project, it's a code for referencing the
            project. Otherwise, it's null.
          example: PR001
        secureurl:
          type: string
          description: |
            A secure URL to the Assignable.
          example: https://smartsheet.com/some/path
          readOnly: true
        secureurl_expiration:
          type: string
          format: date-time
          description: The date (in UTC) when the secure URL expires.
          example: '3000-01-01T00:00:00Z'
          readOnly: true
        timeentry_lockout:
          type: integer
          format: int32
          minimum: -1
          default: -1
          description: >
            If the Assignable is a project, the lockout indicates whether the
            project locks out new time entries and, if so, the number of days
            previous that entries are locked. If the Assignable isn't a project,
            this value is `-1`.


            Valid values:


            | **Value** | **Description** |

            | ------------- | --------------- |

            | `-1` | Not locked |

            | `0` | Locked 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](/api/resource_management/openapi/phases) inherit the
            project's `timeentry_lockout`.
        project_state_id:
          type: integer
          format: int64
          minimum: 1
          example: 8544040
          readOnly: true
          description: >
            A state ID for the project, if the Assignable is a project.
            Otherwise, the value is null.
        thumbnail:
          type: string
          description: >
            A thumbnail image for the project, if the Assignable is a project.
            Otherwise, the value is null.


            **Note:** you can't set a thumbnail for a project via the API -- to
            add a thumbnail, use the application UI. 
          example: >-
            https://10kftprojectimages.s3.amazonaws.com/a62ffd30-316f-4cb6-9c7f-eca45d07a35d/499af1a7-bc6b-446f-8535-4472e6159246.png
          readOnly: true
        owner_id:
          type: integer
          format: int64
          minimum: 1
          readOnly: true
          description: >
            Project owner ID, if the Assignable is a project. Otherwise, the
            value is null.
          example: 11223344
        owner_name:
          type: string
          description: >
            Project owner name, if the Assignable is a project. Otherwise, the
            value is null.
          readOnly: true
        client:
          type: string
          description: >
            Client name, if the Assignable is a project. Otherwise, the value is
            null.
          example: Your Client
    AssignableProject:
      title: Assignable Project
      type: object
      allOf:
        - $ref: '#/components/schemas/AssignableLeaveType'
        - type: object
          properties:
            archived:
              type: boolean
              description: |
                `true` if the project is archived; `false` otherwise.
              example: false
            archived_at:
              type: string
              format: date-time
              description: |
                Date the project was archived.
              readOnly: true
            use_parent_bill_rates:
              type: boolean
              description: >
                If `true` and the project has a parent project, the project uses
                the parent project's bill rates. 
              example: false
            project_state:
              type: string
              enum:
                - Confirmed
                - Tentative
                - Internal
              default: Confirmed
              description: |
                Describes the state of the project.
    AssignmentCoreAttributes:
      title: Assignment
      type: object
      required:
        - allocation_mode
        - starts_at
        - ends_at
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          readOnly: true
          example: 889
          description: The unique identifier for the assignment.
        user_id:
          type: integer
          format: int64
          minimum: 1
          example: 5612
          description: The ID of the user this assignment belongs to.
        assignable_id:
          type: integer
          format: int64
          minimum: 1
          example: 1234
          description: >-
            The ID of the project, phase, or leave type to which the the
            assignment applies.
        starts_at:
          type: string
          format: date
          example: '2025-09-17'
          description: The assignment's effective start date.
        ends_at:
          type: string
          format: date
          example: '2025-12-17'
          description: The assignment's effective end date.
        repetition_id:
          type: integer
          format: int64
          minimum: 1
          example: 886
          nullable: true
          description: >
            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.
        created_at:
          type: string
          format: date-time
          example: '2025-08-27T12:00:00Z'
          readOnly: true
          description: The time of creation.
        updated_at:
          type: string
          format: date-time
          example: '2025-08-27T12:00:00Z'
          readOnly: true
          description: The time of the last update.
        all_day_assignment:
          type: boolean
          example: true
          readOnly: true
        resource_request_id:
          type: integer
          format: int64
          minimum: 1
          nullable: true
          example: null
        bill_rate:
          type: number
          format: number
          example: 100
          nullable: true
          readOnly: true
          description: The cost value.
        bill_rate_id:
          type: integer
          format: int64
          minimum: 1
          nullable: true
          example: 58776516
        status:
          nullable: true
        status_option_id:
          type: integer
          format: int64
          minimum: 1
          nullable: true
          example: 1234567890
          description: The ID of the status option associated with the assignment.
        description:
          type: string
          example: ''
          description: Describes the assignment.
        note:
          type: boolean
          nullable: true
          example: null
          description: Calls out ancillary information about the assignment.
    AssignmentPercentAllocation:
      title: Assignment - percent-based allocation
      type: object
      description: An assignment set to a percentage of the resource's time.
      allOf:
        - type: object
          properties:
            allocation_mode:
              type: string
              enum:
                - percent
              example: percent
              description: >-
                This indicates that a percentage of the resource's time is
                allocated to the corresponding assignment.
            percent:
              type: number
              minimum: 0
              maximum: 1
              example: 0.2
              description: >
                The percentage of time the resource is allocated to the
                corresponding assignment. 


                **Note:** This property is only present when `allocation_mode`
                is `"percent"`.
          required:
            - percent
        - $ref: '#/components/schemas/AssignmentCoreAttributes'
    AssignmentFixedHoursAllocation:
      title: Assignment - fixed-hours-based allocation
      type: object
      description: An assignment set for a fixed number of hours.
      allOf:
        - type: object
          properties:
            allocation_mode:
              type: string
              enum:
                - fixed_hours
              example: fixed_hours
              description: >-
                This indicates that a fixed number of the resource's hours is
                allocated to the corresponding assignment.
            fixed_hours:
              type: number
              minimum: 0
              example: 20
              description: >
                The number of hours the resource is allocated to a corresponding
                assignment. 


                **Note:** This property is only present when `allocation_mode`
                is `"fixed_hours"`.
          required:
            - fixed_hours
        - $ref: '#/components/schemas/AssignmentCoreAttributes'
    AssignmentHoursPerDayAllocation:
      title: Assignment - hours-per-day-based allocation
      type: object
      description: An assignment set to hours per day.
      allOf:
        - type: object
          properties:
            allocation_mode:
              type: string
              enum:
                - hours_per_day
              example: hours_per_day
              description: >-
                This indicates that a number of the resource's daily hours is
                allocated to the corresponding assignment.
            hours_per_day:
              type: number
              minimum: 0
              maximum: 24
              example: 6
              description: >
                The number of hours per day that the resource is allocated to a
                corresponding assignment. 


                **Note:** This property is only present when `allocation_mode`
                is `"hours_per_day"`.
          required:
            - hours_per_day
        - $ref: '#/components/schemas/AssignmentCoreAttributes'
    Assignment:
      oneOf:
        - $ref: '#/components/schemas/AssignmentPercentAllocation'
        - $ref: '#/components/schemas/AssignmentFixedHoursAllocation'
        - $ref: '#/components/schemas/AssignmentHoursPerDayAllocation'
    Subtask:
      title: Subtask
      description: A work item that is part of an aassignment (the parent object).
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          readOnly: true
          example: 6789012345
          description: The unique identifier for the subtask.
        assignment_id:
          type: integer
          format: int64
          minimum: 1
          example: 5612
          readOnly: true
          description: The ID of the assignment to which this subtask belongs.
        assignable_id:
          type: integer
          format: int64
          minimum: 1
          example: 1234
          readOnly: true
          description: >-
            The ID of the project, phase, or leave type to which the the
            assignment applies.
        description:
          type: string
          example: Assess risks
          description: Identifies the subtask.
        completed:
          type: boolean
          default: false
          example: false
          description: This is true if the subtask is done; otherwise, it's false.
        updated_at:
          type: string
          format: date-time
          example: '2025-08-27T12:00:00Z'
          readOnly: true
          description: The time of the last update.
        created_at:
          type: string
          format: date-time
          example: '2025-08-27T12:00:00Z'
          readOnly: true
          description: The time of creation.
        updated_by:
          type: integer
          format: int64
          minimum: 1
          description: The ID of the user who last updated this subtask.
          example: 1234567
          readOnly: true
    BillRate:
      title: Bill rate
      type: object
      description: >-
        Represents a bill rate for a user or discipline on an account, project,
        or phase.
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          example: 991618
          description: The unique identifier for the bill rate.
          readOnly: true
        discipline_id:
          type: integer
          format: int64
          minimum: 1
          description: >
            If set to a discipline ID, this bill rate is a discipline-specific
            bill rate.


            This can only be set via the Resource Management application UI.
          nullable: true
          readOnly: true
        role_id:
          type: integer
          format: int64
          minimum: 1
          example: 30
          description: |
            If set to a role ID, this bill rate is a role-specific bill rate.

            This can only be set via the Resource Management application UI.
          nullable: true
          readOnly: true
        assignable_id:
          type: integer
          format: int64
          minimum: 1
          example: 1234
          description: >
            The ID of the project or phase to which the the bill rate applies.


            > **Note:** Account-specific bill rates don't have an
            `assignable_id` value.
          nullable: true
        user_id:
          type: integer
          format: int64
          minimum: 1
          example: 1001
          description: |
            The ID of a user to which the the bill rate applies.
          nullable: true
        rate:
          type: number
          format: float
          example: 100
          description: The cost value.
        starts_at:
          type: string
          format: date
          example: '2025-09-17'
          description: |
            This user bill rate date indicates the rate's effective start date.

            **Note:** This parameter is only applicable to user bill rates.
          nullable: true
        ends_at:
          type: string
          format: date
          example: '2025-12-17'
          description: |
            This user bill rate date indicates the rate's effective end date.

            **Note:** This parameter is only applicable to user bill rates.
          nullable: true
        created_at:
          type: string
          format: date-time
          example: '2025-01-22T06:00:30Z'
          description: The bill rate's creation timestamp.
          readOnly: true
        updated_at:
          type: string
          format: date-time
          example: '2025-01-22T06:13:40Z'
          description: The timestamp of the bill rate's last update.
          readOnly: true
    BudgetItemAmount:
      title: Budget item amount
      description: Budget item amount
      type: number
      nullable: true
      example: 30.5
    BudgetItemType:
      title: Budget item type
      description: |
        The kind of item being budgeted.

        - `"TimeFees"` is for currency-based budgeting ($).
        - `"TimeFeesDays"` is for time-based budgeting (hours). 
        - `"Expenses"` is for non-time-related, currency-based budgeting ($).
      type: string
      enum:
        - TimeFees
        - TimeFeesDays
        - Expenses
      example: TimeFeesDays
    BudgetItem:
      title: Budget item
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          description: Unique identifier for the resource instance.
          example: 6789
          readOnly: true
        amount:
          $ref: '#/components/schemas/BudgetItemAmount'
        assignable_id:
          type: integer
          format: int64
          minimum: 1
          description: >-
            Unique identifier of the project or phase to which the budget is
            assigned.
          example: 821065
          readOnly: true
        assignable_parent_id:
          type: integer
          format: int64
          minimum: 1
          description: >-
            If the budget is assigned to a phase, it's the unique identifier of
            the phase's parent project.
          readOnly: true
        category:
          type: string
          description: >
            Genre for the budget item.


            **Expense Categories** are classifications of non-labor or
            time-related project costs. These are predefined categories, with
            optional organizational guidelines for per-item cost, that you can
            use when defining a project budget. When entering an expense, you
            and your team members choose which category best represents the
            expense. Examples of expense categories might be travel, printing,
            or materials.
        item_type:
          $ref: '#/components/schemas/BudgetItemType'
        peritem_amount:
          type: number
          description: |
            Currency-based cost for a predefined expense item.
        peritem_label:
          type: string
          description: |
            Name of an expense item that has a predefined cost.
        created_at:
          type: string
          format: date-time
          description: |
            The item's creation timestamp.
          example: '2025-01-22T06:00:30Z'
          readOnly: true
        updated_at:
          type: string
          format: date-time
          description: |
            Timestamp of the most recent modification. 
          example: '2025-01-22T06:13:40Z'
          readOnly: true
    CustomFieldNamespace:
      title: Custom field namespace
      type: string
      description: The category for the custom field.
      enum:
        - assignables
        - users
    CustomFieldDataType:
      title: Custom field data type
      type: string
      description: The kind of data the custom field comprises.
      enum:
        - string
        - selection_list
        - multiple_choice_selection_list
      example: multiple_choice_selection_list
    CustomField:
      title: Custom field
      description: >-
        Custom fields add properties that provide helpful insights for
        scheduling, planning, and reporting.
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          description: The unique identifier of the custom field.
          readOnly: true
        name:
          type: string
          description: The name of the custom field.
          example: Skills
        description:
          type: string
          description: The description of the custom field.
        namespace:
          $ref: '#/components/schemas/CustomFieldNamespace'
        default_value:
          type: string
          description: >
            The value to be applied if none is specified.


            **Important:** If the custom field is a selection list (that is, it
            has drop-down field options), the `default_value` must be one of the
            `options` values or an empty string.
          example: ''
        is_visible_on_info_page:
          type: boolean
          description: If `true`, the custom field is visible on the info page.
          default: true
        is_visible_as_filter:
          type: boolean
          description: If `true`, the custom field is visible as a filter.
          default: false
        is_editable_only_by_admins:
          type: boolean
          description: >
            If `true`, only admins may edit this custom field. 


            **Note:** This property is only applicable to custom fields that
            have `namespace` set to `users`.
          default: false
        created_at:
          type: string
          format: date-time
          description: |
            Project creation date.
          example: '2025-01-22T06:00:30Z'
          readOnly: true
        updated_at:
          type: string
          format: date-time
          description: |
            Date of the most recent modification. 
          example: '2025-01-22T06:13:40Z'
          readOnly: true
        data_type:
          $ref: '#/components/schemas/CustomFieldDataType'
        options:
          type: array
          description: >
            An array of possible values for selection list custom fields.


            This property only applies to custom fields of the following data
            types:


            - `"selection_list"`

            - `"multiple_choice_selection_list"`


            **Important:** On creating a custom field with data type
            `"selection_list"` or `"multiple_choice_selection_list"`, you must
            specify an `options` array.
          items:
            type: string
          example:
            - Audio/Video
            - Graphic Design
            - UX
            - Analytics
            - Python
            - Ruby
            - JavaScript
    Discipline:
      title: Discipline
      type: object
      required:
        - id
        - value
      properties:
        discipline_id:
          type: integer
          format: int64
          minimum: 1
          description: Unique identifier for the discipline.
          example: 1
        value:
          type: string
          description: The name of the discipline.
          example: Developer
    DisciplinesResponse:
      title: Disciplines Response
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/PagingMetadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Discipline'
    BudgetItemCategory:
      title: Budget item category
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          example: 991618
          description: The unique identifier for the budget item category.
          readOnly: true
        category:
          type: string
          description: The category name.
    HolidayItem:
      title: Holiday item
      type: object
      required:
        - id
        - date
        - name
        - created_at
        - updated_at
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          description: Unique identifier for the holiday.
          example: 83019
        date:
          type: string
          format: date
          description: The date of the holiday.
          example: '2022-05-30'
        name:
          type: string
          description: The name of the holiday.
          example: Memorial day
        created_at:
          type: string
          format: date-time
          description: The timestamp when the holiday record was created.
          example: '2022-03-23T16:58:29Z'
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the holiday record was last updated.
          example: '2022-03-23T16:58:29Z'
      description: |
        Details of a single holiday item within the data array.
    LeaveTypeCore:
      title: Leave type core
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          description: Unique identifier for the leave type.
          example: 1
        description:
          type: string
          nullable: true
          description: A detailed description of the leave type. Can be null.
          example: Paid time off
        guid:
          type: string
          format: uuid
          description: A unique GUID for the leave type.
          example: bd5fa048-b3f4-467a-a3b5-18211d488d21
        name:
          type: string
          description: The name of the leave type.
          example: Vacation
        deleted_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when the leave type was deleted. Can be null.
          example: null
          readOnly: true
        created_at:
          type: string
          format: date-time
          description: The time of creation.
          readOnly: true
          example: '2013-09-10T21:31:06Z'
        updated_at:
          type: string
          format: date-time
          description: The time of last update.
          example: '2013-09-10T21:31:06Z'
      required:
        - guid
        - name
    LeaveType:
      title: Assignable Leave type
      type: object
      allOf:
        - $ref: '#/components/schemas/LeaveTypeCore'
        - type: object
          properties:
            type:
              type: string
              description: The object type.
              example: LeaveType
            uid:
              type: string
              description: The globally unique identifier (UID) for the leave type.
              example: leavetype-1234567
    LeaveTypesResponse:
      title: Leave Types Response
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/LeaveType'
        paging:
          type: object
          properties:
            per_page:
              $ref: '#/components/schemas/perPage'
            page:
              type: integer
              format: int32
              description: |
                The current response page number.
              minimum: 1
              default: 1
              example: 2
            previous:
              type: string
              nullable: true
              description: >
                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
              readOnly: true
            self:
              type: string
              description: |
                The path and query parameters to get the current page of items.
              example: /api/v1/users?per_page=1000&page=2
              readOnly: true
            next:
              type: string
              nullable: true
              description: >
                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
              readOnly: true
    Placeholder:
      title: Placeholder
      type: object
      required:
        - id
        - title
        - user_type_id
        - guid
        - displayName
        - type
        - created_at
        - updated_at
        - billrate
      properties:
        id:
          type: integer
          description: Unique identifier for the placeholder resource.
          example: 1543853
        title:
          type: string
          description: The name/title of the placeholder.
          example: IT Admin
        user_type_id:
          type: integer
          description: The numeric code that specifies the user/resource type.
          example: 0
        guid:
          type: string
          format: uuid
          description: The globally unique identifier (GUID) for the resource.
          example: 337e802d-30b8-4abe-a021-0c66e64ba326
        role:
          type: string
          nullable: true
          description: The placeholder's role in the organization.
          example: null
        discipline:
          type: string
          nullable: true
          description: The placeholder's discipline.
          example: null
        location:
          type: string
          nullable: true
          description: The organizational location the placeholder belongs to.
          example: null
        displayName:
          type: string
          description: The displayed name of the placeholder.
          example: IT Admin
        type:
          type: string
          description: The object type.
          example: PlaceholderResource
        thumbnail:
          type: string
          format: uri
          nullable: true
          description: A URL to the placeholder's image thumbnail.
          example: https://assets.rm.smartsheet.com/images/it_admin.png
        abbreviation:
          type: string
          nullable: true
          description: A short abbreviation for the placeholder.
          example: IT
        color:
          type: string
          nullable: true
          description: The color associated with the placeholder in the UI.
          example: Fuchsia
        created_at:
          type: string
          format: date-time
          description: The time of creation.
          readOnly: true
          example: '2022-03-22T18:56:10Z'
        updated_at:
          type: string
          format: date-time
          description: The time of the last update.
          readOnly: true
          example: '2022-04-05T19:47:27Z'
        billrate:
          type: number
          description: The user's billable rate. A value of -1 indicates the default rate.
          example: -1
    PlaceholderResourcesResponse:
      title: Placeholder resources response
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/PagingMetadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Placeholder'
    PlaceholderCreateRequest:
      title: Placeholder create request
      type: object
      description: Parameters for creating a new placeholder.
      required:
        - title
      properties:
        title:
          type: string
          description: An identifier for the placeholder. Required.
          example: Designer
        role:
          type: string
          nullable: true
          description: The placeholder's role.
        discipline:
          type: string
          nullable: true
          description: The placeholder's discipline.
        location:
          type: string
          nullable: true
          description: The organizational location the placeholder belongs to.
    AssignmentsResponse:
      title: Assignments response
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/PagingMetadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Assignment'
      description: >-
        List of assignments for this placeholder. Only included if
        `fields=assignments` is requested.
      readOnly: true
    Tag:
      title: Tag
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          description: Unique identifier for the resource instance.
          example: 1234567
          readOnly: true
        value:
          type: string
          description: |
            Tag name.
          example: New
      required:
        - value
    CustomFieldValueValue:
      title: Custom field value value
      type: string
      example: Effective Growth
      description: >
        The actual value of the custom fields.


        For a custom field that has a `data_type` of
        `multiple_choice_selection_list`, this can be an array of values from
        that list.
    CustomFieldValue:
      title: Custom field value
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          readOnly: true
          example: 9996277
          description: Unique identifier for the custom field value.
        custom_field_name:
          type: string
          readOnly: true
          example: FY Goals
        custom_field_id:
          type: integer
          format: int64
          minimum: 1
          example: 23654
        value:
          $ref: '#/components/schemas/CustomFieldValueValue'
        created_at:
          type: string
          format: date-time
          readOnly: true
          example: '2025-04-11T23:37:21Z'
        updated_at:
          type: string
          format: date-time
          readOnly: true
          example: '2025-04-11T23:37:21Z'
    PhaseCoreAttributesResponse:
      title: Phase core attributes
      description: Phase attributes in response to creating or updating a phase.
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          description: Unique identifier for the phase instance.
          example: 45678901
          readOnly: true
        archived:
          type: boolean
          description: |
            `true` if the phase is archived; `false` otherwise.
          example: false
        archived_at:
          type: string
          format: date-time
          description: |
            Date the phase was archived.
          readOnly: true
        description:
          type: string
          description: |
            Describes the phase.
          example: Plan everything we must do to get this project done.
        guid:
          type: string
          description: |
            Globally Unique Identifier for the user.
          example: d9d0de8f-32cc-4c0b-8af1-648ce039e3f6
          readOnly: true
        name:
          type: string
          description: Phase name.
          example: 'PH001: Plan Phase'
        parent_id:
          type: integer
          format: int64
          minimum: 1
          readOnly: true
          description: >
            If this project has a parent project, this is the parent project ID;
            otherwise, `null`.
          example: 821065
        project_code:
          type: string
          description: |
            A code for referencing the project phase.
          example: PH001
        secureurl:
          type: string
          description: |
            A secure URL to the parent project.
          example: https://smartsheet.com/some/path
          readOnly: true
        secureurl_expiration:
          type: string
          format: date-time
          description: The date (in UTC) when the secure URL expires.
          example: '3000-01-01T00:00:00Z'
          readOnly: true
        timeentry_lockout:
          type: integer
          format: int32
          minimum: -1
          default: -1
          readOnly: true
          description: >
            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:


            | **Value** | **Description** |

            | ------------- | --------------- |

            | `-1` | Not locked |

            | `0` | Locked 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](/api/resource_management/openapi/phases) inherit the
            project's `timeentry_lockout`.
        ends_at:
          type: string
          format: date
          description: |
            The phase's ending date.
          example: '2025-05-29'
        starts_at:
          type: string
          format: date
          description: |
            The phase's starting date.
          example: '2025-01-27'
        deleted_at:
          type: string
          format: date-time
          description: >
            If set, it's the date and time the user was archived; otherwise, the
            user is active.
          readOnly: true
        created_at:
          type: string
          format: date-time
          description: |
            The phase's creation date.
          example: '2025-01-22T06:00:30Z'
          readOnly: true
        updated_at:
          type: string
          format: date-time
          description: |
            Date of the most recent modification. 
          example: '2025-01-22T06:13:40Z'
          readOnly: true
        use_parent_bill_rates:
          type: boolean
          description: |
            If `true`, the phase uses the parent project's bill rates. 
          example: false
        type:
          type: string
          description: |
            The object type.
          example: Project
          readOnly: true
        project_state_id:
          type: integer
          format: int64
          minimum: 1
          example: 8544040
          readOnly: true
        thumbnail:
          type: string
          description: >
            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. 
          example: >-
            https://10kftprojectimages.s3.amazonaws.com/a62ffd30-316f-4cb6-9c7f-eca45d07a35d/499af1a7-bc6b-446f-8535-4472e6159246.png
          readOnly: true
        owner_id:
          type: integer
          format: int64
          minimum: 1
          readOnly: true
          description: |
            Phase owner ID.
          example: 11223344
        owner_name:
          type: string
          description: |
            Phase owner name.
          readOnly: true
          example: Jane Doe
        phase_name:
          type: string
          description: |
            Name of the phase.
          example: Plan
        has_pending_updates:
          type: boolean
          description: |
            `true` if the phase has pending updates; `false` otherwise.
          example: false
          readOnly: true
        client:
          type: string
          description: |
            Client name.
          readOnly: true
          example: Your Client
        project_state:
          type: string
          enum:
            - Confirmed
            - Tentative
            - Internal
          readOnly: true
          default: Confirmed
          description: |
            Describes the state of the project.
        tags:
          type: object
          properties:
            paging:
              $ref: '#/components/schemas/PagingMetadata'
            data:
              type: array
              items:
                $ref: '#/components/schemas/Tag'
          readOnly: true
    Phase:
      title: Phase
      allOf:
        - $ref: '#/components/schemas/PhaseCoreAttributesResponse'
        - type: object
          properties:
            bounding_startdate:
              type: string
              format: date
              description: >
                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`.
              example: '2025-01-01'
              readOnly: true
            bounding_enddate:
              type: string
              format: date
              description: >
                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`.
              example: '2025-07-01'
              readOnly: true
            bounding_startdate_assignables:
              type: string
              format: date
              description: >
                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`.
              example: '2025-01-01'
              readOnly: true
            bounding_enddate_assignables:
              type: string
              format: date
              description: >
                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`.
              example: '2025-07-01'
              readOnly: true
            bounding_startdate_expense_items:
              type: string
              format: date
              description: >
                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`.
              example: '2025-01-01'
              readOnly: true
            bounding_enddate_expense_items:
              type: string
              format: date
              description: >
                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`.
              example: '2025-07-01'
              readOnly: true
            bounding_startdate_time_entries:
              type: string
              format: date
              description: >
                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`.
              example: '2025-01-01'
              readOnly: true
            bounding_enddate_time_entries:
              type: string
              format: date
              description: >
                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`.
              example: '2025-07-01'
              readOnly: true
            bounding_startdate_assignments:
              type: string
              format: date
              description: >
                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`.
              example: '2025-01-01'
              readOnly: true
            bounding_enddate_assignments:
              type: string
              format: date
              description: >
                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`.
              example: '2025-07-01'
              readOnly: true
            custom_field_values:
              type: object
              description: >
                **Note:** This property is only included in responses if the
                `fields` query parameter includes `custom_field_values`.
              properties:
                paging:
                  $ref: '#/components/schemas/PagingMetadata'
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/CustomFieldValue'
              readOnly: true
            confirmed_dollars:
              type: number
              format: float
              example: 160450
              readOnly: true
            approved_hours:
              type: integer
              format: int32
              example: 0
              readOnly: true
            approved_dollars:
              type: number
              example: 0
              readOnly: true
            unconfirmed_hours:
              type: number
              format: double
              example: 87.60000000000002
              readOnly: true
            unconfirmed_dollars:
              type: number
              format: float
              example: 10950
              readOnly: true
            scheduled_hours:
              type: number
              format: double
              example: 1322.400000000003
              readOnly: true
            scheduled_dollars:
              type: number
              format: float
              example: 165300
              readOnly: true
            future_hours:
              type: integer
              format: int32
              example: 0
              readOnly: true
            future_dollars:
              type: number
              example: 0
              readOnly: true
    Project:
      title: Project
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          description: Unique identifier for the resource instance.
          example: 821065
          readOnly: true
        archived:
          type: boolean
          description: |
            `true` if the project is archived; `false` otherwise.
          example: false
        archived_at:
          type: string
          format: date-time
          description: |
            Date the project was archived.
          readOnly: true
        description:
          type: string
          description: |
            Describes the project.
          example: Big pool in a small backyard.
        guid:
          type: string
          description: |
            Globally Unique Identifier for the resource instance.
          example: d9d0de8f-32cc-4c0b-8af1-648ce039e3f6
          readOnly: true
        name:
          type: string
          description: Project name.
          example: 'PR001: Example Project'
        parent_id:
          type: integer
          format: int64
          readOnly: true
          nullable: true
          description: >
            If the object is a Project, this value is null. Otherwise, this
            value is the ID of the parent project.
          example: null
        project_code:
          type: string
          description: |
            A code for referencing the project.
          example: PR001
        secureurl:
          type: string
          description: |
            A secure URL to the project.
          example: https://smartsheet.com/some/path
          readOnly: true
        secureurl_expiration:
          type: string
          format: date-time
          description: The date (in UTC) when the secure URL expires.
          example: '3000-01-01T00:00:00Z'
          readOnly: true
        timeentry_lockout:
          type: integer
          format: int32
          minimum: -1
          default: -1
          description: >
            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:


            | **Value** | **Description** |

            | ------------- | --------------- |

            | `-1` | Not locked |

            | `0` | Locked 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](/api/resource_management/openapi/phases) inherit the
            project's `timeentry_lockout`.
        ends_at:
          type: string
          format: date
          description: |
            The project's ending date.
          example: '2025-05-29'
        starts_at:
          type: string
          format: date
          description: |
            The project's starting date.
          example: '2025-01-27'
        deleted_at:
          type: string
          format: date-time
          description: >
            If set, it's the date and time the project was archived; otherwise,
            the project is active.
          readOnly: true
        created_at:
          type: string
          format: date-time
          description: |
            Project creation date.
          example: '2025-01-22T06:00:30Z'
          readOnly: true
        updated_at:
          type: string
          format: date-time
          description: |
            Date of the most recent modification. 
          example: '2025-01-22T06:13:40Z'
          readOnly: true
        use_parent_bill_rates:
          type: boolean
          description: >
            If `true` and the project has a parent project, the project uses the
            parent project's bill rates. 
          example: false
        type:
          type: string
          description: |
            The object type.
          example: Project
          readOnly: true
        project_state_id:
          type: integer
          format: int64
          minimum: 1
          example: 8544040
          readOnly: true
        thumbnail:
          type: string
          description: >
            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. 
          example: >-
            https://10kftprojectimages.s3.amazonaws.com/a62ffd30-316f-4cb6-9c7f-eca45d07a35d/499af1a7-bc6b-446f-8535-4472e6159246.png
          readOnly: true
        owner_id:
          type: integer
          format: int64
          minimum: 1
          readOnly: true
          description: |
            Project owner ID.
          example: 11223344
        owner_name:
          type: string
          description: |
            Project owner name.
          readOnly: true
        phase_count:
          type: integer
          format: int32
          example: 0
          readOnly: true
        phase_name:
          type: string
          description: |
            Name of the phase.
        has_pending_updates:
          type: boolean
          description: |
            `true` if the project has pending updates; `false` otherwise.
          example: false
          readOnly: true
        client:
          type: string
          description: |
            Client name.
          example: Your Client
        project_state:
          type: string
          enum:
            - Confirmed
            - Tentative
            - Internal
          default: Confirmed
          description: |
            Describes the state of the project.
        tags:
          type: object
          properties:
            paging:
              $ref: '#/components/schemas/PagingMetadata'
            data:
              type: array
              items:
                $ref: '#/components/schemas/Tag'
          readOnly: true
        custom_field_values:
          type: object
          description: >
            **Note:** This property is only included in responses if the
            `fields` query parameter includes `custom_field_values`.
          properties:
            paging:
              $ref: '#/components/schemas/PagingMetadata'
            data:
              type: array
              items:
                $ref: '#/components/schemas/CustomFieldValue'
          readOnly: true
        bounding_startdate:
          type: string
          format: date
          description: >
            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`.
          example: '2025-01-01'
          readOnly: true
        bounding_enddate:
          type: string
          format: date
          description: >
            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`.
          example: '2025-07-01'
          readOnly: true
        bounding_startdate_assignables:
          type: string
          format: date
          description: >
            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`.
          example: '2025-01-01'
          readOnly: true
        bounding_enddate_assignables:
          type: string
          format: date
          description: >
            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`.
          example: '2025-07-01'
          readOnly: true
        bounding_startdate_expense_items:
          type: string
          format: date
          description: >
            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`.
          example: '2025-01-01'
          readOnly: true
        bounding_enddate_expense_items:
          type: string
          format: date
          description: >
            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`.
          example: '2025-07-01'
          readOnly: true
        bounding_startdate_time_entries:
          type: string
          format: date
          description: >
            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`.
          example: '2025-01-01'
          readOnly: true
        bounding_enddate_time_entries:
          type: string
          format: date
          description: >
            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`.
          example: '2025-07-01'
          readOnly: true
        bounding_startdate_assignments:
          type: string
          format: date
          description: >
            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`.
          example: '2025-01-01'
          readOnly: true
        bounding_enddate_assignments:
          type: string
          format: date
          description: >
            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`.
          example: '2025-07-01'
          readOnly: true
        children:
          type: object
          properties:
            paging:
              $ref: '#/components/schemas/PagingMetadata'
            data:
              type: array
              items:
                $ref: '#/components/schemas/Phase'
          readOnly: true
          description: |
            The project phases, if any.
        confirmed_hours:
          type: number
          format: double
          example: 1283.600000000003
          readOnly: true
        confirmed_dollars:
          type: number
          format: float
          example: 160450
          readOnly: true
        approved_hours:
          type: integer
          format: int32
          example: 0
          readOnly: true
        approved_dollars:
          type: number
          example: 0
          readOnly: true
        unconfirmed_hours:
          type: number
          format: double
          example: 87.60000000000002
          readOnly: true
        unconfirmed_dollars:
          type: number
          format: float
          example: 10950
          readOnly: true
        scheduled_hours:
          type: number
          format: double
          example: 1322.400000000003
          readOnly: true
        scheduled_dollars:
          type: number
          format: float
          example: 165300
          readOnly: true
        future_hours:
          type: integer
          format: int32
          example: 0
          readOnly: true
        future_dollars:
          type: number
          example: 0
          readOnly: true
    GenericErrorPayload:
      title: Generic error payload
      type: object
      properties:
        message:
          type: string
          description: Error description.
    ExpenseItem:
      title: Expense item
      type: object
      properties:
        expense_item_id:
          type: integer
          format: int64
          description: Unique identifier for the expense item.
          minimum: 1
          example: 1
          readOnly: true
        assignable_id:
          type: integer
          format: int64
          minimum: 1
          description: ID of the item being assigned.
          example: 32
        assignable_type:
          type: string
          enum:
            - Project
            - LeaveType
            - Phase
          description: The type of the assignable item.
          example: Project
        user_id:
          type: integer
          format: int64
          minimum: 1
          description: ID of the user to whom the item is assigned.
          example: 2
        amount:
          type: number
          format: float
          description: The assigned amount.
          example: 10
        date:
          type: string
          format: date
          description: The date of the expense item.
          example: '2015-04-09'
        category:
          type: string
          nullable: true
          description: The category of the expense item. Can be null.
          example: null
        notes:
          type: string
          nullable: true
          description: Additional notes for the expense item.
          example: Testing exp
        created_at:
          type: string
          format: date-time
          description: Timestamp when the expense item was created.
          example: '2015-04-09T21:54:13Z'
          readOnly: true
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the expense item was last updated.
          example: '2015-04-09T21:54:13Z'
          readOnly: true
      required:
        - id
        - assignable_id
        - user_id
        - amount
        - date
    ExpenseItemsResponse:
      title: Expense items response
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/PagingMetadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/ExpenseItem'
    ProjectMember:
      title: Project member
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          readOnly: true
          example: 1234567
          description: A unique identifier for the user.
        uid:
          type: string
          readOnly: true
          example: user-1234567
          description: A unique identifier for the user's project membership.
        name:
          type: string
          example: Jane Doe
          readOnly: true
          description: The user's first and last name.
        license_type:
          type: string
          enum:
            - licensed
          example: licensed
          description: The user's license type.
    ProjectTagsResponse:
      title: Project tags response
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        paging:
          $ref: '#/components/schemas/PagingMetadata'
    TimeEntry:
      title: Time entry
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          description: Unique identifier for the time entry.
          example: 100000
          readOnly: true
        user_id:
          type: integer
          format: int64
          minimum: 1
          description: >-
            The ID of the user (licensed user only) associated with the time
            entry.
          example: 123
        assignable_id:
          type: integer
          format: int64
          minimum: 1
          description: The ID of the assigned Project, Phase, or Leave Type.
          example: 1001
        assignable_type:
          type: string
          enum:
            - Project
            - LeaveType
          description: The type of the assignable resource.
          example: Project
          readOnly: true
        date:
          type: string
          format: date
          description: The date of the time entry.
          example: '2024-09-12'
        hours:
          type: number
          format: float
          description: The number of hours confirmed. Can be null.
        is_suggestion:
          type: boolean
          description: Indicates if the time entry is a suggestion.
          example: true
          readOnly: true
        scheduled_hours:
          type: number
          nullable: true
          format: float
          description: The number of scheduled hours for the time entry.
          example: 8
          readOnly: true
        task:
          type: string
          nullable: true
          description: The task category. Can be null.
        notes:
          type: string
          nullable: true
          description: Additional notes for the time entry. Can be null.
        bill_rate:
          type: number
          nullable: true
          format: float
          description: The hourly rate for the time entered.
          example: 150
        bill_rate_id:
          type: integer
          nullable: true
          format: int64
          minimum: 1
          description: The ID of the billing rate.
          example: 4
          readOnly: true
        created_at:
          type: string
          format: date-time
          description: Timestamp when the time entry was created.
          example: '2024-09-12T04:32:28Z'
          readOnly: true
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the time entry was last updated.
          example: '2024-09-18T04:32:28Z'
          readOnly: true
      required:
        - user_id
        - assignable_id
        - date
        - hours
    TimeEntriesResponse:
      title: Time entries response
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TimeEntry'
        paging:
          $ref: '#/components/schemas/PagingMetadata'
    TimeEntryCreateRequest:
      title: Time entry create request
      type: object
      required:
        - assignable_id
        - date
        - hours
        - user_id
      properties:
        user_id:
          type: integer
          format: int64
          minimum: 1
          description: User ID (licensed user only).
          example: 123
        assignable_id:
          type: integer
          format: int64
          minimum: 1
          description: Project, Phase or Leave type ID.
          example: 1001
        date:
          type: string
          format: date
          description: The date.
          example: '2012-01-21'
        hours:
          type: number
          description: Number of hours confirmed.
          example: 0.5
        task:
          type: string
          nullable: true
          maxLength: 256
          description: A task category.
          example: Travel
        notes:
          type: string
          nullable: true
          maxLength: 256
          description: A note.
          example: Drive to Seattle, WA
        bill_rate_id:
          type: integer
          format: int64
          minimum: 1
          nullable: true
          description: |
            The rate ID reference.
          example: null
    User:
      title: User
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          description: Unique identifier for the resource instance.
          example: 1234567
          readOnly: true
        first_name:
          type: string
          description: |
            First name.
          example: Jane
        last_name:
          type: string
          description: |
            Surname.
          example: Doe
        display_name:
          type: string
          description: |
            Display name.
          example: Jane Doe
          readOnly: true
        email:
          type: string
          description: |
            Email address.
          example: jane.doe@smartsheet.com
        user_type_id:
          type: integer
          format: int32
          description: >
            A numeric code that specifies the user's permission level.


            **Permission Level Codes:**


            | **Code** | **Permission level** |

            | ---------------- | -------------------- |

            | 0                | None                 |

            | 1                | Resourcing Administrator |

            | 2                | Portfolio Editor     |

            | 3                | Portfolio Reporter   |

            | 4                | Portfolio Viewer     |

            | 5                | Contractor           |

            | 7                | People Scheduler     |

            | 8                | Project Editor       |


            > **Note:** Unlisted values you may encounter are for internal
            purposes or future use.


            You may set the `user_type_id` to any value except `1` (Resourcing
            Administrator). To make a user a Resourcing Administrator, use the
            app.
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
            - 7
            - 8
          example: 0
        billable:
          type: boolean
          description: |
            `true` if the user is billable; `false` otherwise.
          default: false
          example: true
          readOnly: true
        hire_date:
          type: string
          format: date-time
          description: |
            Date (in UTC) the user was hired.
          example: '2021-07-09T00:00:00Z'
        termination_date:
          type: string
          format: date-time
          nullable: true
          description: |
            Date (in UTC) the user's employment was terminated.
          example: null
        mobile_phone:
          type: string
          description: |
            Cell phone number.
        office_phone:
          type: string
          description: |
            Office phone number.
        archived:
          type: boolean
          description: |
            `true` if the user has been archived; `false` otherwise.

            > **Note:**
            > - An account owner cannot be archived.
            > - An archived user can be unarchived. 
          example: false
        archived_at:
          type: string
          format: date-time
          nullable: true
          description: |
            Date the user was archived.
          readOnly: true
        account_owner:
          type: boolean
          description: |
            `true` if the user is the account owner; `false` otherwise.
          example: false
          readOnly: true
        invitation_pending:
          type: boolean
          description: |
            `true` if an invitation is pending for the user; `false` otherwise.
          example: false
          readOnly: true
        guid:
          type: string
          description: |
            Globally Unique Identifier for the user.
          example: 96d769c7-1b4e-4b07-8baf-5ed6f2b915aa
          readOnly: true
        employee_number:
          type: string
          description: |
            The user's employee number.
          example: ''
        role:
          type: string
          description: |
            The user's role.
          example: Senior
        discipline:
          type: string
          description: |
            The user's field.
          example: Program Management
        location:
          type: string
          description: |
            The user's geographic location.
          example: Seattle
        type:
          type: string
          description: |
            The object type.
          example: User
          readOnly: true
        license_type:
          type: string
          description: |
            The user's license type. 
          enum:
            - licensed
            - managed_resource
          example: licensed
        billability_target:
          type: number
          format: float
          description: >
            The percentage of the resource's available time (based on working
            days/hours settings and part-time availability) that the resource is
            expected to have work assigned. It's on utilization reports to
            compare with the actual percentage.
          example: 100
        billrate:
          type: integer
          format: int32
          description: >
            The currency amount that a resource is "billed out" to clients on an
            hourly basis. Bill rates are inherited from the bill rate matrix in
            Account Settings, but can be overridden in specific resource
            profiles. Bill rates are considered in Time & Fees and Budget
            reports.
          example: -1
        has_login:
          type: boolean
          description: |
            `true` if the user has a setup login; `false` otherwise.
          example: true
          readOnly: true
        login_type:
          type: string
          description: |
            The user's authentication method.

            Possible values:

            - `smar` - Sign in with Smartsheet
            - `saml` - Security Assertion Markup Language
            - `default` - Username/password authentication
          enum:
            - smar
            - saml
            - default
          example: smar
          readOnly: true
        thumbnail:
          type: string
          description: |
            A URL to the user's profile image.
          readOnly: true
        approver_user_ids:
          type: array
          items:
            type: integer
            format: int64
            minimum: 1
          description: |
            IDs of other users who approve this user's timesheets.
          example:
            - 123
            - 456
            - 789
        approvee_user_ids:
          type: array
          items:
            type: integer
            format: int64
            minimum: 1
          description: |
            IDs of other users whose timesheets this user approves.
          example:
            - 222
            - 333
            - 444
        last_login_time:
          type: string
          format: date-time
          description: |
            Date
          example: '2025-02-17T19:12:36Z'
          readOnly: true
        created_at:
          type: string
          format: date-time
          description: |
            Date
          example: '2024-11-13T20:38:10Z'
          readOnly: true
        updated_at:
          type: string
          format: date-time
          description: |
            Date
          example: '2024-11-13T20:38:10Z'
          readOnly: true
    UsersProjectResponse:
      title: Users per project response
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        paging:
          $ref: '#/components/schemas/PagingMetadata'
    ProjectMembership:
      title: Project membership
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          example: 1122334
          description: Unique identifier for the project.
        uid:
          type: string
          example: project-1122334
          description: Universal ID for the project.
        name:
          type: string
          example: 'PR001: Example Project'
          description: Project name.
    FilterCondition:
      title: Filter Condition
      type: object
      required:
        - operation
        - values
      properties:
        operation:
          type: string
          enum:
            - inclusion
            - exclusion
        values:
          type: array
          description: >-
            The values to include or exclude. `[none]` can be used to represent
            a null value.
          items:
            oneOf:
              - type: integer
              - type: string
          example:
            - 432
            - 561
            - 642
    CustomFieldFilterCondition:
      title: Custom field filter condition
      type: object
      required:
        - id
        - operation
        - values
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          description: The custom field ID.
          example: 4321
        operation:
          type: string
          enum:
            - inclusion
            - exclusion
        values:
          type: array
          description: The values to include or exclude.
          items:
            type: string
            example: E
    ReportFilters:
      title: Report filters object
      description: >
        A map of attributes to filter on. Keys are attribute names (e.g.,
        `project_id`, `people_tags`, `custom_fields`), and values are filter
        specifications.
      type: object
      properties:
        client:
          $ref: '#/components/schemas/FilterCondition'
        people_tags:
          $ref: '#/components/schemas/FilterCondition'
        project_id:
          $ref: '#/components/schemas/FilterCondition'
        custom_fields:
          type: array
          description: >-
            Custom field filters require an array of objects specifying ID,
            operation, and values.
          items:
            $ref: '#/components/schemas/CustomFieldFilterCondition'
          example:
            - id: 4321
              operation: inclusion
              values:
                - E
                - S
                - R
    ReportRequestParams:
      title: Report request parameters
      type: object
      required:
        - view
        - time_frame
        - group_by
      properties:
        view:
          type: string
          description: The name of the report view, which determines the columns returned.
          default: time_fees_hours
          enum:
            - time_fees_hours
            - time_fees_days
            - time_fees_amounts
            - time_fees_hours_and_amounts
            - time_fees_days_and_amounts
            - budgets_hours
            - budgets_days
            - budgets_amounts
            - utilization
            - expenses
          example: time_fees_hours
        time_frame:
          description: >-
            The time frame for the report. Can be a shortcut string or a custom
            object.
          oneOf:
            - type: string
              enum:
                - 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
              default: this_week
              example: this_week
            - type: object
              properties:
                from:
                  type: string
                  format: date
                  description: Effective start date (YYYY-MM-DD).
                  example: '2018-01-01'
                to:
                  type: string
                  format: date
                  description: Effective end date (YYYY-MM-DD).
                  example: '2018-12-31'
              required:
                - from
                - to
        group_by:
          type: array
          description: Attributes to group and sort rows by (up to 5 levels).
          items:
            type: string
            enum:
              - user_id
              - role
              - discipline
              - location
              - assignment_status
              - date
              - week
              - month
              - project_id
              - client
              - leave_type
              - project_type
              - project_state
              - phase_name
              - record_type
              - entry_type
              - category
              - approval_status
              - approved_by
          example:
            - client
            - user_id
        filters:
          $ref: '#/components/schemas/ReportFilters'
        today:
          type: string
          format: date
          description: >-
            The date on which past/incurred time ends and future scheduled time
            begins (YYYY-MM-DD). The default value is the current UTC date
            (YYYY-MM-DD).
          example: '2018-03-28'
        calc_incurred_using:
          type: string
          description: >-
            Method for calculating incurred time. Default is
            `confirmed-unconfirmed`.
          default: confirmed-unconfirmed
          enum:
            - confirmed-unconfirmed
            - confirmed
            - approved
          example: confirmed-unconfirmed
    ReportRow:
      title: Report row
      description: >-
        A single row of the generated report. The exact properties depend on the
        `view`.
      type: object
      properties:
        project_id:
          type: integer
          format: int64
          minimum: 1
        project_name:
          type: string
        user_id:
          type: integer
          format: int64
          minimum: 1
        user_name:
          type: string
        incurred_hours:
          type: number
        scheduled_hours:
          type: number
        difference_from_past_scheduled_hours:
          type: number
        future_scheduled_hours:
          type: number
        total_hours:
          type: number
    ReportRowsResponse:
      title: Report rows response
      type: object
      required:
        - rows
      properties:
        params:
          type: object
          description: The request parameters used to generate the report.
        dates:
          type: object
          properties:
            today:
              type: string
              format: date
            range:
              type: object
              properties:
                from:
                  type: string
                  format: date
                to:
                  type: string
                  format: date
        rows:
          type: array
          items:
            $ref: '#/components/schemas/ReportRow'
    ReportTotalsResponse:
      title: Report totals response
      type: object
      properties:
        total_incurred_hours:
          type: number
        total_scheduled_hours:
          type: number
    Role:
      title: Role
      type: object
      required:
        - id
        - value
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          description: Unique identifier for the role.
          example: 1
        value:
          type: string
          description: The name of the role.
          example: Senior
    RolesResponse:
      title: Roles response
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/PagingMetadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Role'
    StatusOption:
      title: Status option
      type: object
      required:
        - id
        - color
        - label
        - stage
        - order
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          description: The unique identifier for the status option.
        color:
          type: string
          enum:
            - blue_bright
            - blue_dark
            - green_bright
            - green_dark
            - yellow
            - orange
            - red
            - purple
            - gray
          description: The color of the status option.
          example: green_bright
        label:
          type: string
          description: The label for the status option.
          example: On Track
        stage:
          type: string
          enum:
            - planned
            - in_progress
            - done
          description: The stage of the status option.
          example: in_progress
        order:
          type: number
          description: A float number used for sorting.
          example: 100
        created_at:
          type: string
          format: date-time
          description: The time of creation.
          readOnly: true
        updated_at:
          type: string
          format: date-time
          description: The time of the last update.
          readOnly: true
        deleted_at:
          type: string
          format: date-time
          nullable: true
          description: The time the status option was deleted.
          readOnly: true
    StatusOptionsResponse:
      title: Status options response
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/StatusOption'
        paging:
          $ref: '#/components/schemas/PagingMetadata'
    Availability:
      title: Availability
      type: object
      required:
        - id
        - user_id
        - day0
        - day1
        - day2
        - day3
        - day4
        - day5
        - day6
        - starts_at
        - ends_at
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          description: The unique identifier for the availability block.
          example: 52
        user_id:
          type: integer
          format: int64
          minimum: 1
          description: The ID of the user this availability block belongs to.
          example: 269
        day0:
          type: number
          description: Available hours on Sunday.
          example: 0
        day1:
          type: number
          description: Available hours on Monday.
          example: 8
        day2:
          type: number
          description: Available hours on Tuesday.
          example: 8
        day3:
          type: number
          description: Available hours on Wednesday.
          example: 4
        day4:
          type: number
          description: Available hours on Thursday.
          example: 8
        day5:
          type: number
          description: Available hours on Friday.
          example: 8
        day6:
          type: number
          description: Available hours on Saturday.
          example: 0
        starts_at:
          type: string
          format: date
          nullable: true
          description: >-
            The effective start date for the availability block. Null implies
            the past.
          example: '2017-01-30'
        ends_at:
          type: string
          format: date
          nullable: true
          description: >-
            The effective end date for the availability block. Null implies the
            future.
          example: '2017-07-28'
        created_at:
          type: string
          format: date-time
          description: The time of creation.
          example: '2024-08-27T12:00:00Z'
        updated_at:
          type: string
          format: date-time
          description: The time of the last update.
          example: '2024-08-27T12:00:00Z'
    AvailabilitiesResponse:
      title: Availabilities response
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/PagingMetadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Availability'
    AvailabilityCreateRequest:
      title: Availability create request
      type: object
      required:
        - day0
        - day1
        - day2
        - day3
        - day4
        - day5
        - day6
      properties:
        starts_at:
          type: string
          format: date
          nullable: true
          description: >-
            The effective start date for the availability block. Null implies
            the past.
          example: '2026-01-30'
        ends_at:
          type: string
          format: date
          nullable: true
          description: >-
            The effective end date for the availability block. Null implies the
            future.
          example: '2026-07-28'
        day0:
          type: number
          description: Available hours on Sunday.
          example: 0
        day1:
          type: number
          description: Available hours on Monday.
          example: 8
        day2:
          type: number
          description: Available hours on Tuesday.
          example: 8
        day3:
          type: number
          description: Available hours on Wednesday.
          example: 4
        day4:
          type: number
          description: Available hours on Thursday.
          example: 8
        day5:
          type: number
          description: Available hours on Friday.
          example: 8
        day6:
          type: number
          description: Available hours on Saturday.
          example: 0
    ExpenseItemCreateRequest:
      title: Expense item create request
      type: object
      required:
        - date
        - amount
        - user_id
      oneOf:
        - title: Use project_id
          type: object
          required:
            - project_id
        - title: Use leave_type_id
          type: object
          required:
            - leave_type_id
        - title: Use assignable_id
          type: object
          required:
            - assignable_id
      properties:
        date:
          type: string
          format: date
          description: The date the expense was reported.
          example: '2015-04-09'
        amount:
          type: number
          description: The amount of the expense.
          example: 10
        project_id:
          type: integer
          format: int64
          minimum: 1
          description: The ID of the project.
          example: 32
        leave_type_id:
          type: integer
          format: int64
          minimum: 1
          description: The ID of the leave type.
          example: 32
        assignable_id:
          type: integer
          format: int64
          minimum: 1
          description: The ID of the assignable (project or leave type).
          example: 32
        category:
          type: string
          nullable: true
          description: The category of the expense.
          example: null
        notes:
          type: string
          nullable: true
          description: Notes for the expense item.
          example: Testing exp
    ExpenseItemUpdateRequest:
      title: Expense item update request
      type: object
      required:
        - date
        - amount
      properties:
        date:
          type: string
          format: date
          description: The updated date the expense was reported. (Required to overwrite)
          example: '2055-04-09'
        amount:
          type: number
          description: The updated amount of the expense. (Required to overwrite)
          example: 555
        category:
          type: string
          nullable: true
          description: The category of the expense.
          example: Travel
        notes:
          type: string
          nullable: true
          description: Notes for the expense item.
          example: Updated notes for client meeting.
    Status:
      title: Status
      type: object
      required:
        - id
        - created_at
        - updated_at
        - user_id
        - status
      properties:
        assignable_id:
          type: integer
          nullable: true
          description: >-
            The ID of the assignable (such as project or leave type) the user is
            currently working on.
          example: 4
        created_at:
          type: string
          format: date-time
          description: The time the status was created.
          readOnly: true
          example: '2013-09-12T14:33:05Z'
        current_task:
          type: string
          nullable: true
          description: The name of the current task.
          example: null
        end:
          type: string
          format: date-time
          nullable: true
          description: The end date of the status.
          example: null
        id:
          type: integer
          format: int64
          minimum: 0
          description: The unique ID of the status.
          example: 1
        message:
          type: string
          nullable: true
          description: A message associated with the status.
          example: Hacking away
        start:
          type: string
          format: date-time
          nullable: true
          description: The start date of the status.
          example: null
        status:
          type: string
          description: The status of the user.
          enum:
            - ITO
            - WFH
            - SIC
            - OOO
            - VAC
            - OOF
          example: ITO
        updated_at:
          type: string
          format: date-time
          description: The time the status was last updated.
          example: '2013-09-12T14:33:05Z'
        user_id:
          type: integer
          format: int64
          minimum: 1
          description: The ID of the user.
          example: 1
    UserStatusesResponse:
      title: User statuses response
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Status'
        paging:
          $ref: '#/components/schemas/PagingMetadata'
    StatusCreateRequest:
      title: Status create request
      type: object
      required:
        - status
      properties:
        status:
          type: string
          description: The status of the user.
          enum:
            - ITO
            - WFH
            - SIC
            - OOO
            - VAC
            - OOF
          example: OOO
        assignable_id:
          type: integer
          nullable: true
          description: The ID of the assignable.
          example: 4
        current_task:
          type: string
          nullable: true
          description: The name of the current task.
          example: Finalizing reports
        end:
          type: string
          format: date-time
          nullable: true
          description: The end date of the status.
          example: '2025-09-01T17:00:00Z'
        message:
          type: string
          nullable: true
          description: A message associated with the status.
          example: In a meeting
        start:
          type: string
          format: date-time
          nullable: true
          description: The start date of the status.
          example: '2025-09-01T09:00:00Z'
    UserTagsResponse:
      title: User tags response
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        paging:
          $ref: '#/components/schemas/PagingMetadata'
    Webhook:
      title: Webhook
      type: object
      required:
        - id
        - url
        - status
        - event_type
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          description: Unique identifier for the webhook.
          example: 123456
        url:
          type: string
          format: uri
          description: URL associated with the webhook, to which events are posted.
          example: https://hooks.example.com/process_webhooks
        status:
          type: string
          enum:
            - active
          description: >-
            The status of the webhook. Currently, the only valid status for a
            webhook is `active`.
          example: active
        event_type:
          type: string
          enum:
            - project.created
            - project.updated
            - time.entry.created
            - time.entry.updated
            - user.created
            - user.updated
            - assignment.created
            - assignment.updated
          description: The type of event associated with the webhook.
          example: project.created
        organization_id:
          type: integer
          format: int64
          minimum: 1
          description: Unique identifier for the organization.
          example: 1
        created_at:
          type: string
          format: date-time
          description: The time the webhook was created.
          readOnly: true
        updated_at:
          type: string
          format: date-time
          description: The time the webhook was last updated.
          readOnly: true
    WebhooksResponse:
      title: Webhooks response
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Webhook'
        paging:
          $ref: '#/components/schemas/PagingMetadata'
    WebhookCreateRequest:
      title: Webhook create request
      type: object
      required:
        - event_type
        - url
      properties:
        url:
          type: string
          format: uri
          description: >-
            URL to which events should be posted. Must be an HTTPS URL with a
            valid host.
          example: https://hooks.example.com/process_webhooks
        event_type:
          type: string
          enum:
            - project.created
            - project.updated
            - time.entry.created
            - time.entry.updated
            - user.created
            - user.updated
            - assignment.created
            - assignment.updated
          description: The type of event associated with the webhook.
          example: project.created
security:
  - AuthToken: []
