openapi: 3.2.0 info: title: Bench Project Roles API description: 'Versioning The API is currently at version 1.0.' version: '1.0' servers: - url: https://bench.gobridgit.com description: Bridgit Bench production security: - {} tags: - name: Project Roles paths: /rp/api/v1/accounts/{accountId}/projects/{projectId}/roles: get: tags: - Project Roles summary: Gets all roles in the given account's project description: 'Permissions Role: Read Finance: Read' operationId: ProjectRoles_Query parameters: - name: accountId in: path description: The Account ID required: true schema: type: integer format: int32 - name: projectId in: path description: The project ID the role belongs to 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' - name: roleState in: query description: '(Optional) Filters the result by the state of the role dates: Current, Upcoming, Past, or All' schema: enum: - Past - Current - Upcoming - All type: string default: All - name: type in: query description: (Optional)Salaried role type to filter results by (Defaults to Operations) schema: enum: - Operations - Preconstruction - All type: string default: Operations responses: '200': description: Success content: text/plain: schema: type: array items: $ref: '#/components/schemas/RoleResponse' application/json: schema: type: array items: $ref: '#/components/schemas/RoleResponse' text/json: schema: type: array items: $ref: '#/components/schemas/RoleResponse' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden post: tags: - Project Roles summary: Add role for the given account's project description: 'Permissions Role: Write Finance: Read' operationId: ProjectRoles_Add parameters: - name: accountId in: path description: The Account ID required: true schema: type: integer format: int32 - name: projectId in: path description: The project ID the role belongs to required: true schema: type: integer format: int64 requestBody: description: The request information for the role creation content: application/json-patch+json: schema: $ref: '#/components/schemas/BaseRoleRequest' application/json: schema: $ref: '#/components/schemas/BaseRoleRequest' text/json: schema: $ref: '#/components/schemas/BaseRoleRequest' application/*+json: schema: $ref: '#/components/schemas/BaseRoleRequest' required: true responses: '201': description: Success content: text/plain: schema: $ref: '#/components/schemas/RoleResponse' application/json: schema: $ref: '#/components/schemas/RoleResponse' text/json: schema: $ref: '#/components/schemas/RoleResponse' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: Unprocessable Entity - Validation failures /rp/api/v1/accounts/{accountId}/projects/{projectId}/roles/bulk: post: tags: - Project Roles summary: Bulk add roles for the given account's project description: 'Permissions Role: Write Finance: Read' operationId: ProjectRoles_BulkAdd parameters: - name: accountId in: path description: The Account ID required: true schema: type: integer format: int32 - name: projectId in: path description: The project ID the role belongs to required: true schema: type: integer format: int64 requestBody: description: The request information for the role creation content: application/json-patch+json: schema: minItems: 1 type: array items: $ref: '#/components/schemas/BaseRoleRequest' application/json: schema: minItems: 1 type: array items: $ref: '#/components/schemas/BaseRoleRequest' text/json: schema: minItems: 1 type: array items: $ref: '#/components/schemas/BaseRoleRequest' application/*+json: schema: minItems: 1 type: array items: $ref: '#/components/schemas/BaseRoleRequest' required: true responses: '200': description: Success content: text/plain: schema: type: array items: $ref: '#/components/schemas/RoleResponse' application/json: schema: type: array items: $ref: '#/components/schemas/RoleResponse' text/json: schema: type: array items: $ref: '#/components/schemas/RoleResponse' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: Unprocessable Entity - Validation failures delete: tags: - Project Roles summary: Remove role by IDs in the given account's project description: 'Permissions Role: Write' operationId: ProjectRoles_BulkRemove parameters: - name: accountId in: path description: The Account ID required: true schema: type: integer format: int32 - name: projectId in: path description: The project ID that the role belongs to required: true schema: type: integer format: int64 requestBody: description: The role IDs for removal content: application/json-patch+json: schema: minItems: 1 type: array items: type: integer format: int64 application/json: schema: minItems: 1 type: array items: type: integer format: int64 text/json: schema: minItems: 1 type: array items: type: integer format: int64 application/*+json: schema: minItems: 1 type: array items: type: integer format: int64 required: true responses: '204': description: No Content - Success '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden /rp/api/v1/accounts/{accountId}/projects/{projectId}/roles/{id}: get: tags: - Project Roles summary: Get role by ID in the given account's project description: 'Permissions Role: Read Finance: Read' operationId: ProjectRoles_Get parameters: - name: accountId in: path description: The Account ID required: true schema: type: integer format: int32 - name: projectId in: path description: The project ID that the role belongs to required: true schema: type: integer format: int64 - name: id in: path description: The role ID required: true schema: type: integer format: int64 responses: '200': description: Success content: text/plain: schema: $ref: '#/components/schemas/RoleResponse' application/json: schema: $ref: '#/components/schemas/RoleResponse' text/json: schema: $ref: '#/components/schemas/RoleResponse' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden put: tags: - Project Roles summary: Update role by ID in the given account's project. description: 'Permissions Role: Write Finance: Read' operationId: ProjectRoles_Update parameters: - name: accountId in: path description: The Account ID required: true schema: type: integer format: int32 - name: projectId in: path description: The project ID that the role belongs to required: true schema: type: integer format: int64 - name: id in: path description: The role ID required: true schema: type: integer format: int64 requestBody: description: The request information for the role update content: application/json-patch+json: schema: $ref: '#/components/schemas/RoleUpdateRequest' application/json: schema: $ref: '#/components/schemas/RoleUpdateRequest' text/json: schema: $ref: '#/components/schemas/RoleUpdateRequest' application/*+json: schema: $ref: '#/components/schemas/RoleUpdateRequest' required: true responses: '200': description: Success content: text/plain: schema: $ref: '#/components/schemas/RoleResponse' application/json: schema: $ref: '#/components/schemas/RoleResponse' text/json: schema: $ref: '#/components/schemas/RoleResponse' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: Unprocessable Entity - Validation failures delete: tags: - Project Roles summary: Remove role by ID in the given account's project description: 'Permissions Role: Write' operationId: ProjectRoles_Remove parameters: - name: accountId in: path description: The Account ID required: true schema: type: integer format: int32 - name: projectId in: path description: The project ID that the role belongs to required: true schema: type: integer format: int64 - name: id in: path description: The role ID required: true schema: type: integer format: int64 responses: '204': description: No Content - Success '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden /rp/api/v1/accounts/{accountId}/projects/{projectId}/roles/{id}/externalId: put: tags: - Project Roles summary: Updates a role to set an external ID that can be referenced by external systems operationId: ProjectRoles_SetExternalId parameters: - name: accountId in: path description: The Account ID required: true schema: type: integer format: int32 - name: projectId in: path description: The Project ID required: true schema: type: integer format: int64 - name: id in: path description: The Role ID required: true schema: type: integer format: int64 requestBody: description: Details for the external Id 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 components: schemas: ProjectRoleTagEntity: type: object properties: id: type: integer format: int64 collectionId: type: integer format: int64 name: type: - string - 'null' collectionName: type: - string - 'null' collectionColor: type: - string - 'null' additionalProperties: false description: Represents a role tag with its collection metadata ExternalIdRequest: type: object properties: externalId: type: - string - 'null' additionalProperties: false RoleCrewResponse: type: object properties: id: type: integer description: Crew id (`crew.id`). format: int64 example: 42 name: type: - string - 'null' description: Crew display name. example: Concrete crew A memberCount: type: integer description: 'Number of people on the crew roster (`crewmember`) for the linked crew. This is the crew''s roster size — not the number of people allocated to this specific role.' format: int32 example: 5 trade: $ref: '#/components/schemas/RoleCrewTradeResponse' additionalProperties: false description: 'Crew summary embedded on a ResourcePlanning.Contracts.RoleResponse when the role is tagged with a crew (`projectrole.crew_id` not null). Loaded from the related `crew` row; cached and serialized via MessagePack for role payloads.' RoleCrewTradeResponse: type: object properties: id: type: integer description: Trade id (`crewtrade.id`). format: int64 example: 1 name: type: - string - 'null' description: Trade display name. example: Electrician colour: type: - string - 'null' description: Trade colour as a hex string; one of ResourcePlanning.Common.Validation.CrewTradeColourAttribute.AllowedHexValues. example: '#D6F0F5' additionalProperties: false description: 'Trade summary embedded on ResourcePlanning.Contracts.RoleCrewResponse.Trade. Slim projection of ResourcePlanning.Contracts.CrewTradeResponse (omits `inUse` and `createdOn`).' RoleNotificationData: type: object properties: notifiedOn: type: string format: date-time recipientIds: type: - array - 'null' items: type: integer format: int64 additionalProperties: false RoleUnfilled: type: object properties: startDate: type: string format: date-time example: '2019-01-01' endDate: type: string format: date-time example: '2020-12-31' additionalProperties: false BaseRoleRequest: type: object properties: name: type: - string - 'null' example: Project Engineer taskId: type: - string - 'null' format: uuid example: a2c09162-dbd8-4079-947d-fbc412061de5 startDate: type: string format: date-time example: '2019-01-01' endDate: type: string format: date-time example: '2020-12-31' skillSet: type: - array - 'null' items: type: integer format: int64 example: - 1 - 2 - 3 note: maxLength: 250 minLength: 0 type: - string - 'null' example: Some note categoryId: type: - integer - 'null' format: int64 example: 123 billable: type: boolean example: false allocations: type: - array - 'null' items: $ref: '#/components/schemas/RoleRequirement' roleTagIds: type: - array - 'null' items: type: integer format: int64 assignmentBreakdownBy: enum: - Custom - Phases - Monthly - Weekly type: - string - 'null' additionalProperties: false RoleHire: type: object properties: isHireRequired: type: boolean hireDescription: type: - string - 'null' previousIsHireRequired: type: boolean hireStatus: enum: - Hire - Hired type: - string - 'null' previousHireStatus: enum: - Hire - Hired type: - string - 'null' taggedByUserId: type: - integer - 'null' format: int32 taggedAt: type: - string - 'null' format: date-time hiredAt: type: - string - 'null' format: date-time additionalProperties: false RoleResponse: type: object properties: id: type: integer format: int64 example: 123 taskId: type: - string - 'null' format: uuid example: 00000000-0000-0000-0000-000000000000 nameId: type: integer format: int64 example: 1 name: type: - string - 'null' example: Project Engineer roleCost: type: - number - 'null' format: double example: 123.45 startDate: type: string format: date-time example: '2019-01-01' endDate: type: string format: date-time example: '2020-12-31' type: enum: - Salaried - Hourly - All type: string example: Salaried skillSet: type: - array - 'null' items: type: integer format: int64 example: '[1,2,3]]' isFilled: type: boolean example: false billable: type: boolean example: false allocations: type: - array - 'null' items: $ref: '#/components/schemas/RoleRequirement' unfilledRanges: type: - array - 'null' items: $ref: '#/components/schemas/RoleUnfilled' note: type: - string - 'null' categoryId: type: - integer - 'null' format: int64 notification: $ref: '#/components/schemas/RoleNotificationData' isCommunicated: type: boolean readOnly: true relatedTitles: type: - array - 'null' items: type: string externalId: type: - string - 'null' createdBy: type: integer format: int32 createdOn: type: string format: date-time hire: $ref: '#/components/schemas/RoleHire' roleTags: type: - array - 'null' items: $ref: '#/components/schemas/ProjectRoleTagEntity' assignmentBreakdownBy: enum: - Custom - Phases - Monthly - Weekly type: - string - 'null' assignedPersonId: type: - integer - 'null' format: int64 assignedPersonName: type: - string - 'null' crew: $ref: '#/components/schemas/RoleCrewResponse' additionalProperties: false RoleRequirement: type: object properties: startDate: type: string format: date-time example: '2019-01-01' endDate: type: string format: date-time example: '2020-12-31' allocatedPercent: maximum: 100 minimum: 0 type: integer format: int32 example: 100 additionalProperties: false RoleUpdateRequest: type: object properties: id: type: integer format: int64 removeSetup: type: boolean expandAllocations: type: boolean shiftDates: type: boolean crewId: type: - integer - 'null' format: int64 startTime: type: - string - 'null' format: date-span endTime: type: - string - 'null' format: date-span workDays: type: - array - 'null' items: enum: - 0 - 1 - 2 - 3 - 4 - 5 - 6 type: integer format: int32 name: type: - string - 'null' example: Project Engineer taskId: type: - string - 'null' format: uuid example: a2c09162-dbd8-4079-947d-fbc412061de5 startDate: type: string format: date-time example: '2019-01-01' endDate: type: string format: date-time example: '2020-12-31' skillSet: type: - array - 'null' items: type: integer format: int64 example: - 1 - 2 - 3 note: maxLength: 250 minLength: 0 type: - string - 'null' example: Some note categoryId: type: - integer - 'null' format: int64 example: 123 billable: type: boolean example: false allocations: type: - array - 'null' items: $ref: '#/components/schemas/RoleRequirement' roleTagIds: type: - array - 'null' items: type: integer format: int64 assignmentBreakdownBy: enum: - Custom - Phases - Monthly - Weekly type: - string - 'null' additionalProperties: false securitySchemes: Bearer: type: http description: Standard Authorization header using the Bearer scheme scheme: bearer bearerFormat: JWT