Projects API

• List projects
• Get a single project
• Create a project
• Update a project
• Archive a project
• Trash a project
• Restore a project
• Fields

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": "pro-product",
          "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": "pro-product",
          "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:

• /projects/completed : List all completed projects
• /projects/open : List all open projects
• /projects/managed_by_me : List all projects which manager is the API user

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": "pro-product",
      "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": "pro-product",
      "name": "Widget International"
    }
  },
  "program": "Manufacturing Improvements",
  "service": {
    "id": 41,
    "name": "Warehouse Management",
    "provider": {
      "id": 44,
      "name": "Widget Data Center,  External IT",
      "account": {
        "id": "pro-product",
        "name": "Widget International"
      }
    },
    "localized_name": "Warehouse Management"
  },
  "source": "R-Service",
  "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.