The Persons API from Bridgit — 11 operation(s) for persons.
openapi: 3.0.4
info:
title: Bench AccountActivities Persons API
description: "<h2>Versioning</h2>\n<p>\n The API is currently at version <code>1.0</code>. All API endpoints (other than\n authentication) require you to specify the API version as part of the path.\n</p>\n\n<h2>URL Paths</h2>\n<p>\n Authentication requests should be made to <code>/auth/signin</code>,\n as documented below. All other API requests should be made to\n sub-paths of <code>/rp/api/1.0/...</code>.\n</p>\n\n<h2>Authentication</h2>\n<p>\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 <code>/auth/signin</code>, 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</p>\n<p>\n The response will be a JSON object including both\n <b>\"access_token\"</b> and <b>\"refresh_token\"</b> property.\n All other requests against the Bench API should include an\n authorization header: <code>Authorization: Bearer xxxYYYzzz</code>,\n where <b>xxxYYYzzz</b> is the value of <b>\"access_token\"</b> in the response.\n <br><br>\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</p>\n\n<p>\n The refresh token can be used to generate new session by request with <code>/auth/token</code> 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</p>\n<p>\n Note that once the refresh token is used, the previous access and refresh token is no longer valid.\n <br><br>\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</p>\n\n<h2>Pagination</h2>\n<p>\n Several of the API endpoints are paginated. These are denoted by\n including the <code>offset</code> (zero-based offset) and <code>limit</code> query\n parameters. For example, to request the <code>10</code> items,\n set the <code>offset=0</code> to <code>limit=10</code>.\n <br>\n NOTE: the result set contains items with index of 0-9\n <br>\n To request the next 10 items (starting at index 10),\n set the <code>offset=10</code> to <code>limit=10</code>\n</p>\n<p>\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 <code>query-has-more: true</code> header in the response.\n</p>\n\n<h2>Request Encoding</h2>\n<p>\n <code>GET</code> and <code>DELETE</code> requests should have parameters encoded as URL query\n parameters. Boolean values should be encoded as <code>true</code> and\n <code>false</code>, not as <code>1</code> and <code>0</code>.\n</p>\n\n<h2>Errors</h2>\n<p>\n Errors are returned for some response codes such as <code>400 Bad Request</code> 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</p>\n"
version: '1.0'
servers:
- url: https://bench.gobridgit.com
description: Bridgit Bench production
security:
- {}
tags:
- name: Persons
paths:
/rp/api/v1/accounts/{accountId}/Persons:
get:
tags:
- Persons
summary: Gets all people in the given account.
description: '<strong>NOTE:</strong> If there are more persons in the account than were returned, there will be a "query-has-more" header that will be set to true.<br/><strong>Permissions</strong><br/>HourlyProfile: Read<br/>Person: Read<br/>Finance: Read'
operationId: Persons_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: email
in: query
description: Filter user with email
schema:
type: string
- name: state
in: query
description: 'If specified and not ''Unknown'', only include people matching the given state. The available values are defined as follows:
- Unknown: By default, includes only Active people.
- Active: include only Active people
- Deactivated: include only Deactivated people
- All: include all people, regardless of state'
schema:
enum:
- Active
- Deactivated
- All
type: string
default: Active
- name: ids
in: query
description: Optional paramater of comma delimited ids for filtering results based on the person IDs provided
schema:
type: array
items:
type: integer
format: int64
- name: uniqueId
in: query
description: Optional paramater of unique identifier for filtering results based on the person unique identifier provided
schema:
type: string
responses:
'200':
description: 'Success: List of persons in the account'
content:
text/plain:
schema:
type: array
items:
$ref: '#/components/schemas/PersonResponse'
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PersonResponse'
text/json:
schema:
type: array
items:
$ref: '#/components/schemas/PersonResponse'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
post:
tags:
- Persons
summary: Add a person to the given account
description: '<br/><strong>Permissions</strong><br/>HourlyProfile: Write<br/>Person: Write<br/>Private: Read<br/>Finance: Read'
operationId: Persons_Post
parameters:
- name: accountId
in: path
description: The Account ID
required: true
schema:
type: integer
format: int32
requestBody:
description: 'Details for the person object and any associated custom field values. Note: the title must be one of the titles already defined on the account.'
content:
application/json-patch+json:
schema:
$ref: '#/components/schemas/NewPersonRequest'
example:
email: jayne@example.com
uniqueId: jayne@example.com
name: Jayne Peters
type: Salaried
title: Project Engineer
photoUrl: https://www.example.com/jayne.png
employmentDates:
StartDate: '2020-01-01T00:00:00'
EndDate: '2020-12-31T00:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
fields:
- fieldId: 1394
values:
- '5195555555'
groupings: null
industryStartDate: null
application/json:
schema:
$ref: '#/components/schemas/NewPersonRequest'
example:
email: jayne@example.com
uniqueId: jayne@example.com
name: Jayne Peters
type: Salaried
title: Project Engineer
photoUrl: https://www.example.com/jayne.png
employmentDates:
StartDate: '2020-01-01T00:00:00'
EndDate: '2020-12-31T00:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
fields:
- fieldId: 1394
values:
- '5195555555'
groupings: null
industryStartDate: null
text/json:
schema:
$ref: '#/components/schemas/NewPersonRequest'
example:
email: jayne@example.com
uniqueId: jayne@example.com
name: Jayne Peters
type: Salaried
title: Project Engineer
photoUrl: https://www.example.com/jayne.png
employmentDates:
StartDate: '2020-01-01T00:00:00'
EndDate: '2020-12-31T00:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
fields:
- fieldId: 1394
values:
- '5195555555'
groupings: null
industryStartDate: null
application/*+json:
schema:
$ref: '#/components/schemas/NewPersonRequest'
example:
email: jayne@example.com
uniqueId: jayne@example.com
name: Jayne Peters
type: Salaried
title: Project Engineer
photoUrl: https://www.example.com/jayne.png
employmentDates:
StartDate: '2020-01-01T00:00:00'
EndDate: '2020-12-31T00:00:00'
workDays:
- 1
- 2
- 3
- 4
- 5
fields:
- fieldId: 1394
values:
- '5195555555'
groupings: null
industryStartDate: null
required: true
responses:
'200':
description: 'Success: Person model of the newly added person'
content:
text/plain:
schema:
$ref: '#/components/schemas/PersonResponse'
application/json:
schema:
$ref: '#/components/schemas/PersonResponse'
text/json:
schema:
$ref: '#/components/schemas/PersonResponse'
'400':
description: Bad Request - Request has missing or invalid values
'401':
description: Unauthorized
'403':
description: Forbidden - User doesn't have permissions on this resource, or the account couldn't be found
'409':
description: Conflict - A person with the provided email already exists on the account
'422':
description: Unprocessable Entity - Validation failure
/rp/api/v1/accounts/{accountId}/Persons/availabilities:
get:
tags:
- Persons
summary: Gets the number of days until each person in this account is available and their availability ranges for the duration
description: '<br/><strong>Permissions</strong><br/>HourlyProfile: Read<br/>Person: Read'
operationId: Persons_QueryNextAvailables
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: start
in: query
description: Start date to filter availabilities from (default today UTC)
schema:
type: string
format: date-time
- name: end
in: query
description: End date to filter availabilities to (default 10 years from today UTC)
schema:
type: string
format: date-time
- name: boundRange
in: query
description: Setting this value to true will truncate the dates returned to the specified start and end date paramters
schema:
type: boolean
default: true
- name: ids
in: query
description: Optional paramater of comma delimited ids for filtering results based on the person IDs provided
schema:
type: array
items:
type: integer
format: int64
- name: includeUnavailable
in: query
description: 'If this is set to true it will return the availabilities and next available dates even if a person doesn''t have a next availability.
If the person does not have a "nextAvailableDate", then the "availableInDays" property will be -1'
schema:
type: boolean
default: false
responses:
'200':
description: 'Success: List of next availabilities'
content:
text/plain:
schema:
type: array
items:
$ref: '#/components/schemas/PersonNextAvailable'
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PersonNextAvailable'
text/json:
schema:
type: array
items:
$ref: '#/components/schemas/PersonNextAvailable'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
/rp/api/v1/accounts/{accountId}/Persons/{id}/externalId:
put:
tags:
- Persons
summary: Updates a person to set and externalId that can be referenced by external systems.
operationId: Persons_SetExternalId
parameters:
- name: accountId
in: path
description: The Account ID
required: true
schema:
type: integer
format: int32
- name: id
in: path
description: The person ID
required: true
schema:
type: integer
format: int64
requestBody:
description: Details for the person 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}/Persons/_filter:
post:
tags:
- Persons
summary: Gets all people in the given account filter by person ids.
description: '<strong>NOTE:</strong> If there are more persons in the account than were returned, there will be a "query-has-more" header that will be set to true.<br/><strong>Permissions</strong><br/>HourlyProfile: Read<br/>Person: Read<br/>Finance: Read'
operationId: Persons_QueryFilter
parameters:
- name: accountId
in: path
description: The Account ID
required: true
schema:
type: integer
format: int32
requestBody:
description: Filter object including personIds, state, email, uniqueId, relativeDate, offset and limit
content:
application/json-patch+json:
schema:
$ref: '#/components/schemas/PersonFilterPredicatesFilter'
application/json:
schema:
$ref: '#/components/schemas/PersonFilterPredicatesFilter'
text/json:
schema:
$ref: '#/components/schemas/PersonFilterPredicatesFilter'
application/*+json:
schema:
$ref: '#/components/schemas/PersonFilterPredicatesFilter'
required: true
responses:
'200':
description: 'Success: List of persons in the account'
content:
text/plain:
schema:
type: array
items:
$ref: '#/components/schemas/PersonResponse'
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PersonResponse'
text/json:
schema:
type: array
items:
$ref: '#/components/schemas/PersonResponse'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
/rp/api/v1/accounts/{accountId}/Persons/{id}:
patch:
tags:
- Persons
summary: Update a person 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.
description: '<br/><strong>Permissions</strong><br/>Person: Write<br/>HourlyProfile: Write<br/>Finance: Read'
operationId: Persons_Update
parameters:
- name: accountId
in: path
description: The Account ID
required: true
schema:
type: integer
format: int32
- name: id
in: path
description: The Person ID
required: true
schema:
type: integer
format: int64
requestBody:
description: 'Details for the person object. Note: the title must be one of the titles already defined on the account.'
content:
application/json-patch+json:
schema:
type: object
additionalProperties: {}
example:
Email: jayne@example.com
UniqueId: This is a unique String Id
Name: Jayne Peters
Title: Project Engineer
EmploymentDates:
StartDate: '2020-01-01T00:00:00'
EndDate: '2020-12-31T00:00:00'
WorkDays:
- 1
- 2
- 3
- 4
- 5
application/json:
schema:
type: object
additionalProperties: {}
example:
Email: jayne@example.com
UniqueId: This is a unique String Id
Name: Jayne Peters
Title: Project Engineer
EmploymentDates:
StartDate: '2020-01-01T00:00:00'
EndDate: '2020-12-31T00:00:00'
WorkDays:
- 1
- 2
- 3
- 4
- 5
text/json:
schema:
type: object
additionalProperties: {}
example:
Email: jayne@example.com
UniqueId: This is a unique String Id
Name: Jayne Peters
Title: Project Engineer
EmploymentDates:
StartDate: '2020-01-01T00:00:00'
EndDate: '2020-12-31T00:00:00'
WorkDays:
- 1
- 2
- 3
- 4
- 5
application/*+json:
schema:
type: object
additionalProperties: {}
example:
Email: jayne@example.com
UniqueId: This is a unique String Id
Name: Jayne Peters
Title: Project Engineer
EmploymentDates:
StartDate: '2020-01-01T00:00:00'
EndDate: '2020-12-31T00:00:00'
WorkDays:
- 1
- 2
- 3
- 4
- 5
required: true
responses:
'200':
description: 'Success: Person model of the updated person'
content:
text/plain:
schema:
$ref: '#/components/schemas/PersonResponse'
application/json:
schema:
$ref: '#/components/schemas/PersonResponse'
text/json:
schema:
$ref: '#/components/schemas/PersonResponse'
'400':
description: Bad Request - Request has missing or invalid values
'401':
description: Unauthorized
'403':
description: Forbidden - User doesn't have permissions on this resource, or the person or account couldn't be found
'409':
description: Conflict - A person with the provided email already exists on the account
'422':
description: Unprocessable Entity - Validation failure
get:
tags:
- Persons
summary: Gets details for the given person
description: '<br/><strong>Permissions</strong><br/>Finance: Read<br/>Person: Read<br/>HourlyProfile: Read'
operationId: Persons_Get
parameters:
- name: accountId
in: path
description: The Account ID
required: true
schema:
type: integer
format: int32
- name: id
in: path
description: The Person 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: Person Model for the requested person'
content:
text/plain:
schema:
$ref: '#/components/schemas/PersonResponse'
application/json:
schema:
$ref: '#/components/schemas/PersonResponse'
text/json:
schema:
$ref: '#/components/schemas/PersonResponse'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
delete:
tags:
- Persons
summary: Deactivate a person
description: '<br/><strong>Permissions</strong><br/>Person: Write<br/>HourlyProfile: Write'
operationId: Persons_Delete
parameters:
- name: accountId
in: path
description: The Account ID
required: true
schema:
type: integer
format: int32
- name: id
in: path
description: The Person ID
required: true
schema:
type: integer
format: int64
responses:
'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 account couldn't be found
/rp/api/v1/accounts/{accountId}/Persons/{id}/deactivate:
post:
tags:
- Persons
summary: Deactivate a person with optional deactivation details (reason, notes, would rehire).
description: '<br/><strong>Permissions</strong><br/>Person: Write<br/>HourlyProfile: Write'
operationId: Persons_Deactivate
parameters:
- name: accountId
in: path
description: The Account ID
required: true
schema:
type: integer
format: int32
- name: id
in: path
description: The Person ID
required: true
schema:
type: integer
format: int64
requestBody:
description: Optional deactivation details
content:
application/json-patch+json:
schema:
$ref: '#/components/schemas/PersonDeactivateRequest'
application/json:
schema:
$ref: '#/components/schemas/PersonDeactivateRequest'
text/json:
schema:
$ref: '#/components/schemas/PersonDeactivateRequest'
application/*+json:
schema:
$ref: '#/components/schemas/PersonDeactivateRequest'
responses:
'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 account couldn't be found
/rp/api/v1/accounts/{accountId}/Persons/{id}/allocations:
get:
tags:
- Persons
summary: Get all allocations for the given person within the selected date range.
description: '<br/><strong>Permissions</strong><br/>Role: Read<br/>HourlyRole: Read<br/>Allocation: Read<br/>HourlyAllocation: Read<br/>Person: Read<br/>HourlyProfile: Read'
operationId: Persons_GetAllocations
parameters:
- name: accountId
in: path
description: The Account ID
required: true
schema:
type: integer
format: int32
- name: id
in: path
description: The Person's 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'
- name: start
in: query
description: Start date to filter allocations from
schema:
type: string
format: date-time
- name: end
in: query
description: End date to filter allocations to
schema:
type: string
format: date-time
- name: roleId
in: query
description: Optional parameter to get allocations for a specific role
schema:
type: integer
format: int32
- name: projectState
in: query
description: Optional parameter for filtering results by project state.
schema:
enum:
- Canceled
- Upcoming
- Active
- Complete
- Pursuit
- Lost
- All
type: string
default: All
- name: type
in: query
description: Optional parameter Salaried role type to filter results by (Default to Operations)
schema:
enum:
- Operations
- Preconstruction
- All
type: string
default: Operations
responses:
'200':
description: 'Success: List of allocations'
content:
text/plain:
schema:
type: array
items:
$ref: '#/components/schemas/PersonAllocationResponse'
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PersonAllocationResponse'
text/json:
schema:
type: array
items:
$ref: '#/components/schemas/PersonAllocationResponse'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
/rp/api/v1/accounts/{accountId}/Persons/{id}/projects:
get:
tags:
- Persons
summary: Get all projects that this person is allocated to, including past, present, and future allocations.
description: '<br/><strong>Permissions</strong><br/>Person: Read<br/>HourlyProfile: Read<br/>Allocation: Read<br/>HourlyAllocation: Read'
operationId: Persons_GetProjects
parameters:
- name: accountId
in: path
description: The Account ID
required: true
schema:
type: integer
format: int32
- name: id
in: path
description: The Person 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'
- name: projectState
in: query
description: Optional parameter for filtering results by project state.
schema:
enum:
- Canceled
- Upcoming
- Active
- Complete
- Pursuit
- Lost
- All
type: string
default: All
responses:
'200':
description: Success
content:
text/plain:
schema:
type: array
items:
$ref: '#/components/schemas/PersonProjectResponse'
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PersonProjectResponse'
text/json:
schema:
type: array
items:
$ref: '#/components/schemas/PersonProjectResponse'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
/rp/api/v1/accounts/{accountId}/Persons/current-projects:
get:
tags:
- Persons
summary: Get all projects that any person in the given account has an active allocation for. That is, each allocation's start date is ≦ now and the end date is ≧ now.
description: '<br/><strong>Permissions</strong><br/>Person: Read<br/>Allocation: Read'
operationId: Persons_GetCurrentProjects
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: personIds
in: query
description: Optional paramater of comma delimited ids for filtering results based on the person IDs provided
schema:
type: array
items:
type: integer
format: int64
- nam
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bridgit/refs/heads/main/openapi/bridgit-persons-api-openapi.yml