Projects API

List projects

List all projects for an account:

GET /projects

Response

status: 200 OK
[
  {
    "id": 7345,
    "sourceID": null,
    "subject": "Warehouse Ordering (WHO)",
    "category": "large",
    "status": "in_progress",
    "completion_target_at": "2017-01-13T09:00:00-06:00",
    "completed_at": null,
    "service": {
      "id": 41,
      "name": "Warehouse Management",
      "provider": {
        "id": 44,
        "name": "Widget Data Center,  External IT",
        "account": {
          "id": "widget",
          "name": "Widget International"
        }
      },
      "localized_name": "Warehouse Management"
    },
    "created_at": "2016-11-13T13:17:00-06:00",
    "updated_at": "2016-12-23T05:09:09-06:00"
  },
  {
    "id": 4021,
    "sourceID": null,
    "subject": "Best in Customer Satisfaction (BICS)",
    "category": "medium",
    "status": "in_progress",
    "completion_target_at": "2017-03-21T10:51:00-05:00",
    "completed_at": null,
    "service": {
      "id": 24,
      "name": "Service Management (ITRP)",
      "provider": {
        "id": 44,
        "name": "Widget Data Center,  External IT",
        "account": {
          "id": "widget",
          "name": "Widget International"
        }
      },
      "localized_name": "Service Management (ITRP)"
    },
    "created_at": "2016-08-05T16:12:00-05:00",
    "updated_at": "2017-01-18T16:15:34-06:00"
  }
]

The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of projects.

Predefined Filters

The following predefined filters are available:

Collection Fields

By default the following fields will appear in collections of projects:

id sourceID subject manager category status completion_target_at completed_at service created_at updated_at

Obtain a different set of fields using the ?fields= parameter.

Filtering

Filtering is available for the following fields:

id source sourceID subject category status completion_target_at completed_at service created_at updated_at

Sorting

By default a collection of projects is sorted descending by id.

The following fields are accepted by the ?sort= parameter:

id sourceID subject category status completion_target_at completed_at service created_at updated_at

Response

The response is similar to the response in List projects

Get a single project

GET /projects/:id

Response

status: 200 OK
{
  "category": "large",
  "completed_at": null,
  "completion_reason": null,
  "completion_target_at": "2017-01-13T09:00:00-06:00",
  "created_at": "2016-11-13T13:17:00-06:00",
  "custom_fields": null,
  "customer": {
    "id": 52,
    "name": "Widget North America,  Manufacturing",
    "account": {
      "id": "widget",
      "name": "Widget International"
    }
  },
  "id": 7345,
  "cost_of_effort": "320000.0",
  "cost_of_purchases": "2315000.0",
  "effort": 3200,
  "risk_level": "significant",
  "roi": 6,
  "total_cost": "2635000.0",
  "value": "2800000.0",
  "justification": "improvement",
  "manager": {
    "id": 156,
    "name": "Ellen Brown",
    "account": {
      "id": "widget",
      "name": "Widget International"
    }
  },
  "program": "Manufacturing Improvements",
  "service": {
    "id": 41,
    "name": "Warehouse Management",
    "provider": {
      "id": 44,
      "name": "Widget Data Center,  External IT",
      "account": {
        "id": "widget",
        "name": "Widget International"
      }
    },
    "localized_name": "Warehouse Management"
  },
  "source": "4me",
  "sourceID": null,
  "status": "in_progress",
  "subject": "Warehouse Ordering (WHO)",
  "time_zone": "Central Time (US & Canada)",
  "ui_extension": null,
  "updated_at": "2016-12-23T05:09:09-06:00",
  "work_hours": {
    "id": 42,
    "name": "Monday through Friday, 9:00am until 5:00pm"
  }
}

The response contains these fields.

Create a project

POST /projects

When creating a new project these fields are available.

Response

status: 201 Created
{
  "category": "...",
  "...": "..."
}

The response contains all fields of the created project and is similar to the response in Get a single project

Update a project

PATCH /projects/:id

When updating a project these fields are available.

Response

status: 200 OK
{
  "category": "...",
  "...": "..."
}

The response contains all fields of the updated project and is similar to the response in Get a single project

Archive a project

POST /projects/:id/archive

Moves a given project to the Archive. This action requires the Account Administrator or Directory Administrator role in the account of the project.

Response

status: 200 OK
{
  "archived": "true",
  "category": "...",
  "...": "..."
}

The response contains all fields of the archived project and is similar to the response in Get a single project

Trash a project

POST /projects/:id/trash

Moves a given project to the Trash. This action requires the Account Administrator or Directory Administrator role in the account of the project.

Response

status: 200 OK
{
  "trashed": "true",
  "category": "...",
  "...": "..."
}

The response contains all fields of the archived project and is similar to the response in Get a single project

Restore a project

POST /projects/:id/restore

Moves a given project from the Archive or the Trash back into the view of “Completed Projects”. This action requires the Account Administrator or Directory Administrator role in the account of the project.

Response

status: 200 OK
{
  "category": "...",
  "...": "..."
}

The response contains all fields of the archived project and is similar to the response in Get a single project

Fields

attachments
Readonly aggregated Attachments
Use Projects - Notes API to get note attachments.
category
Optional enum with reference field of Project Category — The Category field is used to select the category of the project.
completed_at
Readonly datetime — The Completed at field is automatically set to the date and time at which the project is saved with the status “Completed”.
completion_reason
Optional enum — The Completion reason field is used to select the appropriate completion reason for the project when it has been completed. It is automatically set to “Complete” when all tasks related to the project have reached the status “Completed”, “Approved” or “Canceled”. Valid values are:
  • withdrawn: Withdrawn - Withdrawn by Requester
  • rejected: Rejected - Rejected by Approver
  • abandoned: Abandoned - Not Implemented
  • partial: Partial - Not Entirely Implemented
  • complete: Complete - Fully Implemented
completion_target_at
Readonly datetime — The Completion target field shows the target date and time of the last task of the project.
cost_of_effort
Optional decimal — The Cost of effort field is used to specify the estimated cost of the effort that will be needed from internal employees and/or long-term contractors to implement the project.
cost_of_purchases
Optional decimal — The Cost of purchases field is used to specify the estimated cost of all purchases (for equipment, consulting effort, licenses, etc.) needed to implement the project. Recurring costs that will be incurred following the implementation of the project are to be included for the entire ROI calculation period.
created_at
Readonly datetime — The date and time at which the project was created.
custom_fields
Optional custom fields — Custom fields provided in JSON format by the UI Extension that is linked to the project.
custom_fields_attachments
Writeonly attachments The attachments used in Custom fields.
customer
Required reference to Organization — The Customer field is used to select the organization for which the project is to be implemented.
effort
Optional integer — The Effort field is used to specify the estimated number of hours of effort that will be needed from internal employees and/or long-term contractors to implement the project.
id
Readonly integer — The unique ID of the project.
justification
Required enum — The Justification field is used to select the reason why the project should be considered for implementation. Valid values are:
  • compliance: Compliance
  • correction: Correction
  • expansion: Expansion
  • improvement: Improvement
  • maintenance: Maintenance
  • move: Move
  • removal: Removal
  • replacement: Replacement
manager
Required reference to Person — The Manager field is used to select the person who is responsible for coordinating the implementation of the project.
note
Optional text (max 64KB) — The Note field is used to provide a high-level description of the project. It is also used to add any information that could prove useful for anyone involved in the project, including the people whose approval is needed and the people who are helping to implement it.

The Note field cannot be specified in the ?fields= parameter.

note_attachments
Writeonly attachments The attachments used in the Note field.
program
Required string (max 80) — The Program field is used to indicate which program the project is a part of. A previously entered program name can be selected, or a new one can be entered.
resolution_duration
Readonly integer — The number of minutes it took to complete this project, which is calculated as the difference between the created_at and completed_at values.
risk_level
Optional enum with reference field of Project Risk Level — The Risk level field is used to select the risk level of the project.
roi
Readonly integer — The ROI field displays the estimated return on investment for the project. This percentage is calculated by dividing the value, minus the total costs, by the total costs and multiplying the result by 100.
service
Required reference to Service — The Service field is used to select the service for which the project will be implemented.
source
Optional string (max 30) - See source
sourceID
Optional string (max 128) - See source
status
Optional enum, default: registered — The Status field is automatically set based on the status of the project’s tasks. Valid values are:
  • registered: Registered
  • in_progress: In Progress
  • progress_halted: Progress Halted
  • completed: Completed
subject
Required string (max 255) — The Subject field is used to enter a short description of the objective of the project.
time_zone
Required time_zone — The Time zone field is used to select the time zone that applies to the selected work hours.
total_cost
Readonly decimal — The Total costs field displays the total estimated cost to implement the project. This is the sum of the estimated cost of effort and cost of purchases.
ui_extension
Readonly reference to UI Extension — The UI extension field indicates the UI extension that is applied to the project.
updated_at
Readonly datetime — The date and time of the last update of the project. If the project has no updates it contains the created_at value.
value
Optional decimal — The Value field is used to specify the estimated financial value that the implementation of the project will deliver for the entire ROI calculation period.
value_currency
Optional enum — The currency of the Value field value of the project. For valid values, see the list of currencies in the Currency field of the Account API.
work_hours
Required reference to Calendar — The Work hours field is used to select a calendar that defines the work hours that are to be used to calculate the anticipated assignment and completion target for the tasks of the project.