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": "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:
/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": "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": "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 Requesterrejected
: Rejected - Rejected by Approverabandoned
: Abandoned - Not Implementedpartial
: Partial - Not Entirely Implementedcomplete
: 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
: Compliancecorrection
: Correctionexpansion
: Expansionimprovement
: Improvementmaintenance
: Maintenancemove
: Moveremoval
: Removalreplacement
: 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
andcompleted_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
: Registeredin_progress
: In Progressprogress_halted
: Progress Haltedcompleted
: 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.