openapi: 3.0.4
info:
title: Bench AccountActivities Projects API
description: "Versioning
\n\n The API is currently at version 1.0. All API endpoints (other than\n authentication) require you to specify the API version as part of the path.\n
\n\nURL Paths
\n\n Authentication requests should be made to /auth/signin,\n as documented below. All other API requests should be made to\n sub-paths of /rp/api/1.0/....\n
\n\nAuthentication
\n\n API requests are authenticated using an OAuth Bearer token.\n You can get a token by authenticating your user by sending a\n POST request to /auth/signin, with \"username and \"password\"\n parameters form-encoded in the body of the request.\n\n POST /auth/signin HTTP/1.1\n Content-Type: application/x-www-form-urlencoded\n\n username=user@example.com&password=some-secret-password\n
\n\n The response will be a JSON object including both\n \"access_token\" and \"refresh_token\" property.\n All other requests against the Bench API should include an\n authorization header: Authorization: Bearer xxxYYYzzz,\n where xxxYYYzzz is the value of \"access_token\" in the response.\n
\n For example:\n\n $ curl https://bench.gobridgit.com/auth/signin -H 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'username=someone@example.com' --data-urlencode 'password=[...snip...]'\n {\n \"access_token\": \"...snip...\",\n \"token_type\": \"Bearer\",\n \"refresh_token\": \"...snip...\"\n \"expiry\": \"2020-01-01T00:00:00.413440849Z\"\n }\n\n
\n\n\n The refresh token can be used to generate new session by request with /auth/token endpoint:\n\n POST /auth/token HTTP/1.1\n Content-Type: application/x-www-form-urlencoded\n\n grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA\n
\n\n Note that once the refresh token is used, the previous access and refresh token is no longer valid.\n
\n For example:\n\n $ curl https://bench.gobridgit.com/auth/token -H 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=refresh_token' --data-urlencode 'refresh_token=[...snip...]'\n {\n \"access_token\": \"...snip...\",\n \"token_type\": \"Bearer\",\n \"refresh_token\": \"...snip...\"\n \"expiry\": \"2020-01-01T00:00:00.413440849Z\"\n }\n
\n\nPagination
\n\n Several of the API endpoints are paginated. These are denoted by\n including the offset (zero-based offset) and limit query\n parameters. For example, to request the 10 items,\n set the offset=0 to limit=10.\n
\n NOTE: the result set contains items with index of 0-9\n
\n To request the next 10 items (starting at index 10),\n set the offset=10 to limit=10\n
\n\n Responses to paginated API endpoints return a JSON array of objects.\n If there are results beyond the page you have requested, the server\n will set a query-has-more: true header in the response.\n
\n\nRequest Encoding
\n\n GET and DELETE requests should have parameters encoded as URL query\n parameters. Boolean values should be encoded as true and\n false, not as 1 and 0.\n
\n\nErrors
\n\n Errors are returned for some response codes such as 400 Bad Request in the\n following format:\n\n {\n \"errors\": [\n {\n \"errorType\": \"ValidationError\",\n \"description\": \"The value of Name must be a string with a minimum length of 1 and a maximum length of 8 and not whitespace.\",\n \"field\": \"Name\",\n \"values\": [\n null\n ]\n }\n ],\n \"title\": \"One or more validation errors occurred.\",\n \"status\": 400,\n \"instance\": \"api/v1/accounts/0/persons\",\n \"requestUid\": \"123e4567-e89b-12d3-a456-426614174000\"\n }\n
\n"
version: '1.0'
servers:
- url: https://bench.gobridgit.com
description: Bridgit Bench production
security:
- {}
tags:
- name: Projects
paths:
/rp/api/v1/accounts/{accountId}/Projects:
get:
tags:
- Projects
summary: Gets all projects in the given account
description: 'NOTE: If there are more projects in the account than were returned, there will be a "query-has-more" header that will be set to true.
Permissions
Project: Read
Role: Read
HourlyRole: Read'
operationId: Projects_Query
parameters:
- name: accountId
in: path
description: The Account ID
required: true
schema:
type: integer
format: int32
- name: relativeDate
in: query
description: Optional paramater used to calculate date based properties. If not provided, it is set to today's date in UTC.
schema:
type: string
format: date-time
example: '2021-01-01'
example: '2021-01-01'
- name: offset
in: query
description: Offset for pagination
schema:
maximum: 2147483647
minimum: 0
type: integer
format: int32
default: 0
- name: limit
in: query
description: Maximum number of results in this page
schema:
maximum: 2147483647
minimum: 1
type: integer
format: int32
default: 1000
- name: name
in: query
description: 'Name filter that affects whether or not to return projects back with/without the name contains partial match (Default: Empty)'
schema:
type: string
- name: issues
in: query
description: 'State filter that affects whether or not to return projects back with/without or any issues (Default: All)'
schema:
enum:
- 0
- 1
- 2
type: integer
format: int32
default: 2
- name: ids
in: query
description: Optional comma delimited list of project IDs to filter the result on
schema:
type: array
items:
type: integer
format: int64
- name: projectState
in: query
description: Optional comma delimited list for filtering results by project state.
schema:
enum:
- Canceled
- Upcoming
- Active
- Complete
- Pursuit
- Lost
- All
type: string
default: All
- name: includeProjectNumber
in: query
description: 'Whether to include the Project Number field in the response (Default: false)'
schema:
type: boolean
default: false
responses:
'200':
description: Success
content:
text/plain:
schema:
type: array
items:
$ref: '#/components/schemas/ProjectResponse'
example:
- id: 8673
name: Ahrens Lofts
colour: '#00FF00'
startDate: '2019-01-01'
endDate: '2020-12-31'
startTime: 08:00:00
endTime: '17:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
state: Active
winPercent: null
unfilledRoles: 3
totalRoles: 16
unfilledHourlyRoles: 4
totalHourlyRoles: 7
totalTasks: 9
unfilledTaskRoles: 0
totalTaskRoles: 0
issuesCount: 5
lastModifiedOn: '2019-01-01T00:00:00'
type: Awarded
currentPhases:
- name: Precon
phases: []
groupings: null
description: Project Description
truncatedDescription: Project Desc
externalId: null
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ProjectResponse'
example:
- id: 8673
name: Ahrens Lofts
colour: '#00FF00'
startDate: '2019-01-01'
endDate: '2020-12-31'
startTime: 08:00:00
endTime: '17:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
state: Active
winPercent: null
unfilledRoles: 3
totalRoles: 16
unfilledHourlyRoles: 4
totalHourlyRoles: 7
totalTasks: 9
unfilledTaskRoles: 0
totalTaskRoles: 0
issuesCount: 5
lastModifiedOn: '2019-01-01T00:00:00'
type: Awarded
currentPhases:
- name: Precon
phases: []
groupings: null
description: Project Description
truncatedDescription: Project Desc
externalId: null
text/json:
schema:
type: array
items:
$ref: '#/components/schemas/ProjectResponse'
example:
- id: 8673
name: Ahrens Lofts
colour: '#00FF00'
startDate: '2019-01-01'
endDate: '2020-12-31'
startTime: 08:00:00
endTime: '17:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
state: Active
winPercent: null
unfilledRoles: 3
totalRoles: 16
unfilledHourlyRoles: 4
totalHourlyRoles: 7
totalTasks: 9
unfilledTaskRoles: 0
totalTaskRoles: 0
issuesCount: 5
lastModifiedOn: '2019-01-01T00:00:00'
type: Awarded
currentPhases:
- name: Precon
phases: []
groupings: null
description: Project Description
truncatedDescription: Project Desc
externalId: null
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
post:
tags:
- Projects
summary: Add a project to the given account
description: 'If you add a project with a type of Awarded, it will be created with a state based on the date.
If you add a project with a type of Opportunity, it will be created with a state of Pursuit.
The "winPercent" is associated with an Opportunity, you can create an Opportunity with a winPercent but not for an Awarded project.
NOTE: Opportunities do not count towards allocation statistics so, any roles and allocations set on the project will not cause conflicts, issues, over-allocations etc.
Permissions
Project: Write
Private: Read
Finance: Read'
operationId: Projects_Post
parameters:
- name: accountId
in: path
description: The Account ID
required: true
schema:
type: integer
format: int32
requestBody:
description: Details for the project object and any associated custom field values.
content:
application/json-patch+json:
schema:
$ref: '#/components/schemas/NewProjectRequest'
example:
name: Ahrens Lofts
colour: '#00FF00'
startDate: '2019-01-01'
endDate: '2020-12-31'
startTime: 08:00:00
endTime: '17:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
type: Awarded
fields:
- fieldId: 1394
values:
- '5195555555'
groupings: null
description: Project Description
phases: null
application/json:
schema:
$ref: '#/components/schemas/NewProjectRequest'
example:
name: Ahrens Lofts
colour: '#00FF00'
startDate: '2019-01-01'
endDate: '2020-12-31'
startTime: 08:00:00
endTime: '17:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
type: Awarded
fields:
- fieldId: 1394
values:
- '5195555555'
groupings: null
description: Project Description
phases: null
text/json:
schema:
$ref: '#/components/schemas/NewProjectRequest'
example:
name: Ahrens Lofts
colour: '#00FF00'
startDate: '2019-01-01'
endDate: '2020-12-31'
startTime: 08:00:00
endTime: '17:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
type: Awarded
fields:
- fieldId: 1394
values:
- '5195555555'
groupings: null
description: Project Description
phases: null
application/*+json:
schema:
$ref: '#/components/schemas/NewProjectRequest'
example:
name: Ahrens Lofts
colour: '#00FF00'
startDate: '2019-01-01'
endDate: '2020-12-31'
startTime: 08:00:00
endTime: '17:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
type: Awarded
fields:
- fieldId: 1394
values:
- '5195555555'
groupings: null
description: Project Description
phases: null
required: true
responses:
'200':
description: Success
content:
text/plain:
schema:
$ref: '#/components/schemas/ProjectResponse'
example:
id: 8673
name: Ahrens Lofts
colour: '#00FF00'
startDate: '2019-01-01'
endDate: '2020-12-31'
startTime: 08:00:00
endTime: '17:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
state: Active
winPercent: null
unfilledRoles: 3
totalRoles: 16
unfilledHourlyRoles: 4
totalHourlyRoles: 7
totalTasks: 9
unfilledTaskRoles: 0
totalTaskRoles: 0
issuesCount: 5
lastModifiedOn: '2019-01-01T00:00:00'
type: Awarded
currentPhases:
- name: Precon
phases: []
groupings: null
description: Project Description
truncatedDescription: Project Desc
externalId: null
application/json:
schema:
$ref: '#/components/schemas/ProjectResponse'
example:
id: 8673
name: Ahrens Lofts
colour: '#00FF00'
startDate: '2019-01-01'
endDate: '2020-12-31'
startTime: 08:00:00
endTime: '17:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
state: Active
winPercent: null
unfilledRoles: 3
totalRoles: 16
unfilledHourlyRoles: 4
totalHourlyRoles: 7
totalTasks: 9
unfilledTaskRoles: 0
totalTaskRoles: 0
issuesCount: 5
lastModifiedOn: '2019-01-01T00:00:00'
type: Awarded
currentPhases:
- name: Precon
phases: []
groupings: null
description: Project Description
truncatedDescription: Project Desc
externalId: null
text/json:
schema:
$ref: '#/components/schemas/ProjectResponse'
example:
id: 8673
name: Ahrens Lofts
colour: '#00FF00'
startDate: '2019-01-01'
endDate: '2020-12-31'
startTime: 08:00:00
endTime: '17:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
state: Active
winPercent: null
unfilledRoles: 3
totalRoles: 16
unfilledHourlyRoles: 4
totalHourlyRoles: 7
totalTasks: 9
unfilledTaskRoles: 0
totalTaskRoles: 0
issuesCount: 5
lastModifiedOn: '2019-01-01T00:00:00'
type: Awarded
currentPhases:
- name: Precon
phases: []
groupings: null
description: Project Description
truncatedDescription: Project Desc
externalId: null
'400':
description: "Bad Request - Request has missing or invalid values\n\n Example when trying to add a project with an invalid colour value:\n{
\"errors\": [
{
\"errorType\": \"ValidationError\",
\"description\": \"colour must be a six-digit hexadecimal number with a '#' in front of it. Ex: #00FF00\",
\"errorCode\": null,
\"field\": \"Colour\",
\"innerException\": null,
\"hResult\": -2146233088
}
],
\"title\": \"One or more validation errors occurred.\",
\"status\": 400,
\"instance\": \"/api/v1/accounts/2/projects\",
\"requestUid\": \"82a530a1-36b1-4a8a-8bd9-9833de5b0cbd\"
}"
'401':
description: Unauthorized
'403':
description: Forbidden - User doesn't have permissions on this resource, or the project couldn't be found.
'409':
description: "Conflict - A project already exists in the account with the same name.\n\n Example when trying to add a project that has the same name as an existing one:\n{
\"errors\": [
{
\"errorType\": \"Duplicate\",
\"description\": \"A project in the account already exists with the requested name.\",
\"errorCode\": null,
\"innerException\": null,
\"hResult\": -2146233088
}
],
\"title\": \"One or more validation errors occurred.\",
\"status\": 409,
\"instance\": \"/api/v1/accounts/2/projects\",
\"requestUid\": \"8ba8f060-858b-46d9-b3cc-fa1c391ebc66\"
}"
/rp/api/v1/accounts/{accountId}/Projects/_filter:
post:
tags:
- Projects
summary: Gets all projects in the given account filter by project ids.
description: 'NOTE: If there are more projects in the account than were returned, there will be a "query-has-more" header that will be set to true.
Permissions
Project: Read
Role: Read
HourlyRole: Read'
operationId: Projects_QueryFilter
parameters:
- name: accountId
in: path
description: The Account ID
required: true
schema:
type: integer
format: int32
requestBody:
description: Filter object including projectIds, projectState, name, issues, relativeDate, offset and limit
content:
application/json-patch+json:
schema:
$ref: '#/components/schemas/ProjectFilterPredicatesFilter'
application/json:
schema:
$ref: '#/components/schemas/ProjectFilterPredicatesFilter'
text/json:
schema:
$ref: '#/components/schemas/ProjectFilterPredicatesFilter'
application/*+json:
schema:
$ref: '#/components/schemas/ProjectFilterPredicatesFilter'
required: true
responses:
'200':
description: 'Success: List of projects in the account'
content:
text/plain:
schema:
type: array
items:
$ref: '#/components/schemas/ProjectResponse'
example:
- id: 8673
name: Ahrens Lofts
colour: '#00FF00'
startDate: '2019-01-01'
endDate: '2020-12-31'
startTime: 08:00:00
endTime: '17:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
state: Active
winPercent: null
unfilledRoles: 3
totalRoles: 16
unfilledHourlyRoles: 4
totalHourlyRoles: 7
totalTasks: 9
unfilledTaskRoles: 0
totalTaskRoles: 0
issuesCount: 5
lastModifiedOn: '2019-01-01T00:00:00'
type: Awarded
currentPhases:
- name: Precon
phases: []
groupings: null
description: Project Description
truncatedDescription: Project Desc
externalId: null
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ProjectResponse'
example:
- id: 8673
name: Ahrens Lofts
colour: '#00FF00'
startDate: '2019-01-01'
endDate: '2020-12-31'
startTime: 08:00:00
endTime: '17:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
state: Active
winPercent: null
unfilledRoles: 3
totalRoles: 16
unfilledHourlyRoles: 4
totalHourlyRoles: 7
totalTasks: 9
unfilledTaskRoles: 0
totalTaskRoles: 0
issuesCount: 5
lastModifiedOn: '2019-01-01T00:00:00'
type: Awarded
currentPhases:
- name: Precon
phases: []
groupings: null
description: Project Description
truncatedDescription: Project Desc
externalId: null
text/json:
schema:
type: array
items:
$ref: '#/components/schemas/ProjectResponse'
example:
- id: 8673
name: Ahrens Lofts
colour: '#00FF00'
startDate: '2019-01-01'
endDate: '2020-12-31'
startTime: 08:00:00
endTime: '17:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
state: Active
winPercent: null
unfilledRoles: 3
totalRoles: 16
unfilledHourlyRoles: 4
totalHourlyRoles: 7
totalTasks: 9
unfilledTaskRoles: 0
totalTaskRoles: 0
issuesCount: 5
lastModifiedOn: '2019-01-01T00:00:00'
type: Awarded
currentPhases:
- name: Precon
phases: []
groupings: null
description: Project Description
truncatedDescription: Project Desc
externalId: null
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
/rp/api/v1/accounts/{accountId}/Projects/{id}/externalId:
put:
tags:
- Projects
summary: Updates a project to set and externalId that can be referenced by external systems.
operationId: Projects_PutExternalId
parameters:
- name: accountId
in: path
description: The Account ID
required: true
schema:
type: integer
format: int32
- name: id
in: path
description: The Project ID
required: true
schema:
type: integer
format: int64
requestBody:
description: Details for the project object
content:
application/json-patch+json:
schema:
$ref: '#/components/schemas/ExternalIdRequest'
application/json:
schema:
$ref: '#/components/schemas/ExternalIdRequest'
text/json:
schema:
$ref: '#/components/schemas/ExternalIdRequest'
application/*+json:
schema:
$ref: '#/components/schemas/ExternalIdRequest'
required: true
responses:
'204':
description: No Content
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
/rp/api/v1/accounts/{accountId}/Projects/{id}:
get:
tags:
- Projects
summary: Gets details for the given project
description: '
Permissions
Project: Read
Role: Read
HourlyRole: Read'
operationId: Projects_Get
parameters:
- name: accountId
in: path
description: The Account ID
required: true
schema:
type: integer
format: int32
- name: id
in: path
description: The Project ID
required: true
schema:
type: integer
format: int64
- name: relativeDate
in: query
description: Optional paramater used to calculate date based properties. If not provided, it is set to today's date in UTC.
schema:
type: string
format: date-time
example: '2021-01-01'
example: '2021-01-01'
responses:
'200':
description: Success
content:
text/plain:
schema:
$ref: '#/components/schemas/ProjectResponse'
example:
id: 8673
name: Ahrens Lofts
colour: '#00FF00'
startDate: '2019-01-01'
endDate: '2020-12-31'
startTime: 08:00:00
endTime: '17:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
state: Active
winPercent: null
unfilledRoles: 3
totalRoles: 16
unfilledHourlyRoles: 4
totalHourlyRoles: 7
totalTasks: 9
unfilledTaskRoles: 0
totalTaskRoles: 0
issuesCount: 5
lastModifiedOn: '2019-01-01T00:00:00'
type: Awarded
currentPhases:
- name: Precon
phases: []
groupings: null
description: Project Description
truncatedDescription: Project Desc
externalId: null
application/json:
schema:
$ref: '#/components/schemas/ProjectResponse'
example:
id: 8673
name: Ahrens Lofts
colour: '#00FF00'
startDate: '2019-01-01'
endDate: '2020-12-31'
startTime: 08:00:00
endTime: '17:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
state: Active
winPercent: null
unfilledRoles: 3
totalRoles: 16
unfilledHourlyRoles: 4
totalHourlyRoles: 7
totalTasks: 9
unfilledTaskRoles: 0
totalTaskRoles: 0
issuesCount: 5
lastModifiedOn: '2019-01-01T00:00:00'
type: Awarded
currentPhases:
- name: Precon
phases: []
groupings: null
description: Project Description
truncatedDescription: Project Desc
externalId: null
text/json:
schema:
$ref: '#/components/schemas/ProjectResponse'
example:
id: 8673
name: Ahrens Lofts
colour: '#00FF00'
startDate: '2019-01-01'
endDate: '2020-12-31'
startTime: 08:00:00
endTime: '17:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
state: Active
winPercent: null
unfilledRoles: 3
totalRoles: 16
unfilledHourlyRoles: 4
totalHourlyRoles: 7
totalTasks: 9
unfilledTaskRoles: 0
totalTaskRoles: 0
issuesCount: 5
lastModifiedOn: '2019-01-01T00:00:00'
type: Awarded
currentPhases:
- name: Precon
phases: []
groupings: null
description: Project Description
truncatedDescription: Project Desc
externalId: null
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
patch:
tags:
- Projects
summary: 'Update a project in the given account. Each of the fields in the request body is optional - only fields that are present in the request will be updated.
When changing the start or end dates for a project, you can customize how the start and end dates for roles and phases will change in response. See the Model below for details.
Note that roles or phases whose start and end dates change such that the start date is after the end date will be automatically deleted from the project.'
description: "To update a project's dates you need the ProjectDates permission, which is separate from the Project Write permission that is required to update other project details. \nThis is because changing project dates can have a significant impact on any associated roles and phases, and therefore only users with the ProjectDates permission should be allowed to make those changes.\n\n\nIf the \"shiftDates\" property is true and you specify a changed project start or end date in this request,\nthen the project's start and end dates, and the start and end dates for all roles and phases\nwill be adjusted by the same amount. If this property is set to true, then you must only send\nEITHER startDate OR endDate - behavior when setting both is to shift with project start date..\n\n \nIf the \"removeRoleSetup\" property is true, then all roles are removed from the given project.\n\n \nIf the \"expandRole\" property is true and you specify a changed project start to be earlier than the\ncurrent start date, or you specify a changed project end date to be later than the current\nend date, then any roles that share the same date will be expanded so that they\nstill start or end on the same date that the project starts or ends. The duration of those\nroles will be expanded in this case.\n\n \nFor example, take a project running from February 1, 2020 to July 1, 2020, where Role A runs from\nFebruary 1, 2020 to March 1, 2020, and Role B runs from February 15, 2020 to July 1, 2020.\nIf a PATCH request is sent with startDate = January 15, 2020 and expandRole = true, then\nthe project will be modified to run from January 15, 2020 to July 1, 2020, role A will be modified\nto run from January 15, 2020 to March 1, 2020, and role B will remain unmodified. If instead you\nspecify expandRole = false, then the roles will be unmodified in this situation.\n\n \nIf the \"expandPhases\" property is true and you specify a changed project start to be earlier than the\ncurrent start date, or you specify a changed project end date to be later than the current\nend date, then any phases that share the same date will be expanded so that they\nstill start or end on the same date that the project starts or ends. The duration of those\nphases will be expanded in this case.\n\n \nFor example, take a project running from February 1, 2020 to July 1, 2020, where Phase A runs from\nFebruary 1, 2020 to March 1, 2020, and Phase B runs from March 2, 2020 to July 1, 2020.\nIf a PATCH request is sent with startDate = January 15, 2020 and expandPhases = true, then\nthe project will be modified to run from January 15, 2020 to July 1, 2020, Phase A will be modified\nto run from January 15, 2020 to March 1, 2020, and Phase B will remain unmodified. If instead you\nspecify expandPhase = false, then the phases will be unmodified in this situation.\n\n \nIf you update a project to a \"type\" of Awarded without specifying a state, it will default to a date based state.\nYou can specify a state, but if you pass Active, Completed or Upcoming the API will ignore those values and return a date based state.\nIf you set it to Canceled it will cancel the project and the allocation stats for the account will no longer be affected by the project.\nYou can re-activate a project by passing Active, Completed or Upcoming and the API will return the proper date based state.\nAn Awarded project can only have a state of Active, Completed, Upcoming or Canceled.\n\nIf you update a project to type of Opportunity without specifying a state, default to a state of Pursuit.\nAn Opportunity can only have a state of Pursuit or Lost.\n\nThe \"winPercent\" is associated with an Opportunity, you can update the winPercent for an Opportunity in Pursuit state but not for an Awarded project.\nNOTE: Opportunities do not count towards allocation statistics so, any roles and allocations set on the project will not cause conflicts, issues, over-allocations etc.
Permissions
Project: Write
ProjectDates: Write
Role: Read
HourlyRole: Read"
operationId: Projects_Update
parameters:
- name: accountId
in: path
description: The Account ID
required: true
schema:
type: integer
format: int32
- name: id
in: path
description: The Project ID
required: true
schema:
type: integer
format: int64
requestBody:
description: Details for the project object
content:
application/json-patch+json:
schema:
type: object
additionalProperties: {}
example:
name: Ahrens Lofts
colour: '#00FF00'
startDate: '2019-01-01T00:00:00'
endDate: '2020-12-31T00:00:00'
startTime: 08:00:00
endTime: '17:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
type: Awarded
state: Active
winPercent: 80
description: Project Description
shiftDates: false
removeRoleSetup: false
expandPhases: false
expandRole: true
application/json:
schema:
type: object
additionalProperties: {}
example:
name: Ahrens Lofts
colour: '#00FF00'
startDate: '2019-01-01T00:00:00'
endDate: '2020-12-31T00:00:00'
startTime: 08:00:00
endTime: '17:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
type: Awarded
state: Active
winPercent: 80
description: Project Description
shiftDates: false
removeRoleSetup: false
expandPhases: false
expandRole: true
text/json:
schema:
type: object
additionalProperties: {}
example:
name: Ahrens Lofts
colour: '#00FF00'
startDate: '2019-01-01T00:00:00'
endDate: '2020-12-31T00:00:00'
startTime: 08:00:00
endTime: '17:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
type: Awarded
state: Active
winPercent: 80
description: Project Description
shiftDates: false
removeRoleSetup: false
expandPhases: false
expandRole: true
application/*+json:
schema:
type: object
additionalProperties: {}
example:
name: Ahrens Lofts
colour: '#00FF00'
startDate: '2019-01-01T00:00:00'
endDate: '2020-12-31T00:00:00'
startTime: 08:00:00
endTime: '17:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
type: Awarded
state: Active
winPercent: 80
description: Project Description
shiftDates: false
removeRoleSetup: false
expandPhases: false
expandRole: true
required: true
responses:
'200':
description: Success
content:
text/plain:
schema:
$ref: '#/components/schemas/ProjectResponse'
example:
id: 8673
name: Ahrens Lofts
colour: '#00FF00'
startDate: '2019-01-01'
endDate: '2020-12-31'
startTime: 08:00:00
endTime: '17:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
state: Active
winPercent: null
unfilledRoles: 3
totalRoles: 16
unfilledHourlyRoles: 4
totalHourlyRoles: 7
totalTasks: 9
unfilledTaskRoles: 0
totalTaskRoles: 0
issuesCount: 5
lastModifiedOn: '2019-01-01T00:00:00'
type: Awarded
currentPhases:
- name: Precon
phases: []
groupings: null
description: Project Description
truncatedDescription: Project Desc
externalId: null
application/json:
schema:
$ref: '#/components/schemas/ProjectResponse'
example:
id: 8673
name: Ahrens Lofts
colour: '#00FF00'
startDate: '2019-01-01'
endDate: '2020-12-31'
startTime: 08:00:00
endTime: '17:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
state: Active
winPercent: null
unfilledRoles: 3
totalRoles: 16
unfilledHourlyRoles: 4
totalHourlyRoles: 7
totalTasks: 9
unfilledTaskRoles: 0
totalTaskRoles: 0
issuesCount: 5
lastModifiedOn: '2019-01-01T00:00:00'
type: Awarded
currentPhases:
- name: Precon
phases: []
groupings: null
description: Project Description
truncatedDescription: Project Desc
externalId: null
text/json:
schema:
$ref: '#/components/schemas/ProjectResponse'
example:
id: 8673
name: Ahrens Lofts
colour: '#00FF00'
startDate: '2019-01-01'
endDate: '2020-12-31'
startTime: 08:00:00
endTime: '17:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
state: Active
winPercent: null
unfilledRoles: 3
totalRoles: 16
unfilledHourlyRoles: 4
totalHourlyRoles: 7
totalTasks: 9
unfilledTaskRoles: 0
totalTaskRoles: 0
issuesCount: 5
lastModifiedOn: '2019-01-01T00:00:00'
type: Awarded
currentPhases:
- name: Precon
phases: []
groupings: null
description: Project Description
truncatedDescription: Project Desc
externalId: null
'400':
description: "Bad Request - Request has missing or invalid values\n\n Example when trying to update a project with an invalid colour value:\n{
\"errors\": [
{
\"errorType\": \"ValidationError\",
\"description\": \"colour must be a six-digit hexadecimal number with a '#' in front of it. Ex: #00FF00\",
\"errorCode\": null,
\"field\": \"Colour\",
\"innerException\": null,
\"hResult\": -2146233088
}
],
\"title\": \"One or more validation errors occurred.\",
\"status\": 400,
\"instance\": \"/api/v1/accounts/2/projects\",
\"requestUid\": \"82a530a1-36b1-4a8a-8bd9-9833de5b0cbd\"
}"
'401':
description: Unauthorized
'403':
description: Forbidden - User doesn't have permissions on this resource, or the project couldn't be found.
'409':
description: "Conflict - A project already exists in the account with the same name.\n\n Example when trying to update a project name to the same name as an existing one:\n{
\"errors\": [
{
\"errorType\": \"Duplicate\",
\"description\": \"A project in the account already exists with the requested name.\",
\"errorCode\": null,
\"innerException\": null,
\"hResult\": -2146233088
}
],
\"title\": \"One or more validation errors occurred.\",
\"status\": 409,
\"instance\": \"/api/v1/accounts/2/projects\",
\"requestUid\": \"8ba8f060-858b-46d9-b3cc-fa1c391ebc66\"
}"
'422':
description: "Unprocessable Entity - Updated end or start date is invalid.\n\n Example when trying to update a project end date that would result in the end date being before the current start date:\n{
\"errors\": [
{
\"errorType\": \"ValidationError\",
\"description\": \"Project new end date cannot be before current project start date\",
\"errorCode\": null,
\"innerException\": null,
\"hResult\": -2146233088
}
],
\"title\": \"One or more validation errors occurred.\",
\"status\": 422,
\"instance\": \"/api/v1/accounts/2/projects/1\",
\"requestUid\": \"fd024b9c-6432-4a38-a5eb-5ee458866620\"
}"
delete:
tags:
- Projects
summary: Delete a project
description: '
Permissions
Project: Write'
operationId: Projects_Delete
parameters:
- name: accountId
in: path
description: The Account ID
required: true
schema:
type: integer
format: int32
- name: id
in: path
description: The Project ID
required: true
schema:
type: integer
format: int64
responses:
'200':
description: OK
'204':
description: No Content (success)
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden - User doesn't have permissions on this resource, or the project couldn't be found
components:
schemas:
FieldValuesPair:
type: object
properties:
fieldId:
type: integer
format: int64
example: 1394
values:
type: array
items:
type: string
nullable: true
example:
- '5195555555'
additionalProperties: false
ExternalIdRequest:
type: object
properties:
externalId:
type: string
nullable: true
additionalProperties: false
ProjectPhaseResponse:
type: object
properties:
id:
type: integer
format: int64
example: 1234
name:
type: string
nullable: true
example: Pre-Construction
startDate:
type: string
format: date-time
example: '2020-01-01'
endDate:
type: string
format: date-time
example: '2020-12-31'
lastModifiedOn:
type: string
format: date-time
example: '2021-05-27T10:58:23.530Z'
additionalProperties: false
ProjectResponse:
type: object
properties:
id:
type: integer
format: int64
example: 8673
name:
type: string
nullable: true
example: Ahrens Lofts
colour:
type: string
description: 'The color associated with the project, expressed as a web color string: a ''#'' character, followed by a six-digit hexadecimal number.'
nullable: true
example: '#4B6BAA'
startDate:
type: string
format: date-time
example: '2019-01-01'
endDate:
type: string
format: date-time
example: '2020-12-31'
startTime:
type: string
format: date-span
example: 08:00:00
endTime:
type: string
format: date-span
example: '17:00:00'
workDays:
type: array
items:
enum:
- 0
- 1
- 2
- 3
- 4
- 5
- 6
type: integer
format: int32
nullable: true
example:
- 1
- 2
- 3
- 4
- 5
state:
enum:
- Canceled
- Upcoming
- Active
- Complete
- Pursuit
- Lost
type: string
example: Active
winPercent:
type: integer
format: int32
nullable: true
example: 100
unfilledRoles:
type: integer
format: int32
example: 3
totalRoles:
type: integer
format: int32
example: 5
unfilledHourlyRoles:
type: integer
format: int32
example: 4
totalHourlyRoles:
type: integer
format: int32
example: 7
totalTasks:
type: integer
format: int32
example: 9
unfilledTaskRoles:
type: integer
format: int32
example: 5
totalTaskRoles:
type: integer
format: int32
example: 5
issuesCount:
type: integer
format: int64
example: 5
lastModifiedOn:
type: string
format: date-time
example: '2019-01-01T00:00:00Z'
type:
enum:
- Awarded
- Opportunity
type: string
example: Awarded
currentPhases:
type: array
items:
$ref: '#/components/schemas/ProjectCurrentPhase'
nullable: true
phases:
type: array
items:
$ref: '#/components/schemas/ProjectPhaseResponse'
nullable: true
groupings:
type: array
items:
type: integer
format: int64
nullable: true
example:
- 1
- 2
- 3
description:
type: string
nullable: true
example: Project Description
truncatedDescription:
type: string
nullable: true
example: Project Desc
externalId:
type: string
nullable: true
projectNumber:
type: string
nullable: true
additionalProperties: false
NewProjectRequest:
type: object
properties:
name:
type: string
nullable: true
example: Ahrens Lofts
colour:
pattern: ^#[0-9a-fA-F]{6}$
type: string
description: 'The color associated with the project, expressed as a web color string: a ''#'' character, followed by a six-digit hexadecimal number. If not provided, color rules will be evaluated.'
nullable: true
example: '#4B6BAA'
startDate:
type: string
format: date-time
example: '2019-01-01'
endDate:
type: string
format: date-time
example: '2020-12-31'
startTime:
type: string
format: date-span
example: 08:00:00
endTime:
type: string
format: date-span
example: '17:00:00'
workDays:
minItems: 1
type: array
items:
enum:
- 0
- 1
- 2
- 3
- 4
- 5
- 6
type: integer
format: int32
nullable: true
example:
- 1
- 2
- 3
- 4
- 5
type:
enum:
- Awarded
- Opportunity
type: string
winPercent:
maximum: 100
minimum: 0
type: integer
format: int32
nullable: true
example: 100
fields:
type: array
items:
$ref: '#/components/schemas/FieldValuesPair'
nullable: true
groupings:
minItems: 1
type: array
items:
type: integer
format: int64
nullable: true
description:
type: string
nullable: true
example: Project Description
phases:
type: array
items:
$ref: '#/components/schemas/ProjectPhaseRequest'
nullable: true
additionalProperties: false
ProjectPhaseRequest:
type: object
properties:
id:
type: integer
format: int64
example: 1234
startDate:
type: string
format: date-time
example: '2020-01-01'
endDate:
type: string
format: date-time
example: '2020-12-31'
additionalProperties: false
ProjectFilterPredicates:
type: object
properties:
projectIds:
type: array
items:
type: integer
format: int64
nullable: true
projectState:
enum:
- Canceled
- Upcoming
- Active
- Complete
- Pursuit
- Lost
- All
type: string
name:
type: string
nullable: true
issues:
enum:
- 0
- 1
- 2
type: integer
format: int32
relativeDate:
type: string
format: date-time
includeProjectNumber:
type: boolean
additionalProperties: false
ProjectCurrentPhase:
type: object
properties:
name:
type: string
nullable: true
example: Precon
additionalProperties: false
ProjectFilterPredicatesFilter:
type: object
properties:
offset:
type: integer
format: int32
limit:
type: integer
format: int32
predicates:
$ref: '#/components/schemas/ProjectFilterPredicates'
additionalProperties: false
securitySchemes:
Bearer:
type: http
description: Standard Authorization header using the Bearer scheme
scheme: bearer
bearerFormat: JWT