The PersonFields API from Bridgit — 2 operation(s) for personfields.
openapi: 3.0.4
info:
title: Bench AccountActivities PersonFields 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: PersonFields
paths:
/rp/api/v1/accounts/{id}/person-fields:
get:
tags:
- PersonFields
summary: Get all the person field definitions on the given account.
description: '<br/><strong>Permissions</strong><br/>Account: Read<br/>Private: Read<br/>Finance: Read<br/>Person: Read<br/>HourlyProfile: Read'
operationId: PersonFields_Query
parameters:
- name: id
in: path
description: The account ID
required: true
schema:
type: integer
format: int32
responses:
'200':
description: 'Success: List of Field Definitions'
content:
text/plain:
schema:
type: array
items:
$ref: '#/components/schemas/PersonFieldDefinitionResponse'
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PersonFieldDefinitionResponse'
text/json:
schema:
type: array
items:
$ref: '#/components/schemas/PersonFieldDefinitionResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
post:
tags:
- PersonFields
summary: Adds or updates person field definitions on the given account.
description: 'If you pass in a FieldDefRequest object without an "id" this endpoint will add a new one to the account if the name isn''t reserved or in use.
If you pass in a FieldDefRequest object with an "id" this endpoint will update an existing one that matches the id.
To add a value or multiple values to a selection list you must pass an array of "definedValues" that contain objects with a "definedValue" property of the value you want to add.
To update a value or multiple values in a selection list you must pass an array of "definedValues" that contain objects with a "valueId" property of the value id to update and a "definedValue" property of the value you want to update it to.
To remove a value or multiple values from a selection list you must pass an array of "definedValues" that contain objects with a "valueId" property of the value id to remove, a "definedValue" property of the value you want to remove, and a "forRemoval" property set to true.
Example: You have a list of "Years" and you want to change "5" to "5-9" and remove values "6" through "9" and add a value of "10+"
<code>[<br/> {<br/> "id": 123,<br/> "name": "Years",<br/> "type": "SingleSelect",<br/> "definedValues": [<br/> {<br/> "valueId": 584,<br/> "definedValue": "5-9",<br/> "forRemoval": false,<br/> "deleteExperienceFieldValues": false<br/> },<br/> {<br/> "valueId": 585,<br/> "definedValue": "6",<br/> "forRemoval": true,<br/> "deleteExperienceFieldValues": false<br/> },<br/> {<br/> "valueId": 586,<br/> "definedValue": "7",<br/> "forRemoval": true,<br/> "deleteExperienceFieldValues": false<br/> },<br/> {<br/> "valueId": 587,<br/> "definedValue": "8",<br/> "forRemoval": true,<br/> "deleteExperienceFieldValues": false<br/> },<br/> {<br/> "valueId": 588,<br/> "definedValue": "9",<br/> "forRemoval": true,<br/> "deleteExperienceFieldValues": false<br/> },<br/> {<br/> "valueId": 0,<br/> "definedValue": "10+",<br/> "forRemoval": false,<br/> "deleteExperienceFieldValues": false<br/> }<br/> ],<br/> "isRequired": true,<br/> "isPrivate": false,<br/> "isLocked": false<br/> }<br/>]</code>
<strong>NOTE:</strong> There are a few reserved field names that cannot be used.
"Person ID","Photo","Name","Title","Next Availability","Current Project","Issues","Email","Hire Date","Termination Date","Allocated People","Next project","Past projects","Next project start","Current project end","Notes","Certifications","Group", "Company Tenure", "Industry Tenure", "Industry Start Date"
<h2>Validation</h2><b>Title</b>: SingleSelect. A list where only 1 value can be selected. When creating the list, each value should be between 1 and 250 non-empty characters.
<b>Title (Hourly)</b>: SingleSelect. A list where only 1 value can be selected. When creating the list, each value should be between 1 and 250 non-empty characters.
<b>Skill Set</b>: Multi List Selection. A list where 0 or more values can be selected. When creating the list, each value should be between 1 and 250 non-empty characters
<b>Skill Set (Hourly)</b>: Multi List Selection. A list where 0 or more values can be selected. When creating the list, each value should be between 1 and 250 non-empty characters
<b>Other</b>: Free text. Max length: 2400
<b>Home Address</b>: Max length: 250
<b>Cost Rate (hr)</b>: Currency. Should be greater or equal to zero, starts with 0 to 15 digits of ```0-9``` then optionally followed by ```.``` with 0 to 2 digits of ```0-9```
<b>Employee ID</b>: Free text. Max length: 250
<b>Date</b>: Format: dd/MM/yyyy
<b>Checkbox</b>: Accepted values: true or false
<br/><strong>Permissions</strong><br/>Account: Write<br/>Private: Read<br/>Finance: Read'
operationId: PersonFields_Post
parameters:
- name: id
in: path
required: true
schema:
type: integer
format: int32
requestBody:
content:
application/json-patch+json:
schema:
minItems: 1
type: array
items:
$ref: '#/components/schemas/FieldDefRequest'
example:
- id: 123
name: Years
type: SingleSelect
definedValues:
- valueId: 584
definedValue: 5-9
forRemoval: false
deleteExperienceFieldValues: false
- valueId: 585
definedValue: '6'
forRemoval: true
deleteExperienceFieldValues: false
- valueId: 586
definedValue: '7'
forRemoval: true
deleteExperienceFieldValues: false
- valueId: 587
definedValue: '8'
forRemoval: true
deleteExperienceFieldValues: false
- valueId: 588
definedValue: '9'
forRemoval: true
deleteExperienceFieldValues: false
- valueId: 0
definedValue: 10+
forRemoval: false
deleteExperienceFieldValues: false
isRequired: true
isPrivate: false
isLocked: false
application/json:
schema:
minItems: 1
type: array
items:
$ref: '#/components/schemas/FieldDefRequest'
example:
- id: 123
name: Years
type: SingleSelect
definedValues:
- valueId: 584
definedValue: 5-9
forRemoval: false
deleteExperienceFieldValues: false
- valueId: 585
definedValue: '6'
forRemoval: true
deleteExperienceFieldValues: false
- valueId: 586
definedValue: '7'
forRemoval: true
deleteExperienceFieldValues: false
- valueId: 587
definedValue: '8'
forRemoval: true
deleteExperienceFieldValues: false
- valueId: 588
definedValue: '9'
forRemoval: true
deleteExperienceFieldValues: false
- valueId: 0
definedValue: 10+
forRemoval: false
deleteExperienceFieldValues: false
isRequired: true
isPrivate: false
isLocked: false
text/json:
schema:
minItems: 1
type: array
items:
$ref: '#/components/schemas/FieldDefRequest'
example:
- id: 123
name: Years
type: SingleSelect
definedValues:
- valueId: 584
definedValue: 5-9
forRemoval: false
deleteExperienceFieldValues: false
- valueId: 585
definedValue: '6'
forRemoval: true
deleteExperienceFieldValues: false
- valueId: 586
definedValue: '7'
forRemoval: true
deleteExperienceFieldValues: false
- valueId: 587
definedValue: '8'
forRemoval: true
deleteExperienceFieldValues: false
- valueId: 588
definedValue: '9'
forRemoval: true
deleteExperienceFieldValues: false
- valueId: 0
definedValue: 10+
forRemoval: false
deleteExperienceFieldValues: false
isRequired: true
isPrivate: false
isLocked: false
application/*+json:
schema:
minItems: 1
type: array
items:
$ref: '#/components/schemas/FieldDefRequest'
example:
- id: 123
name: Years
type: SingleSelect
definedValues:
- valueId: 584
definedValue: 5-9
forRemoval: false
deleteExperienceFieldValues: false
- valueId: 585
definedValue: '6'
forRemoval: true
deleteExperienceFieldValues: false
- valueId: 586
definedValue: '7'
forRemoval: true
deleteExperienceFieldValues: false
- valueId: 587
definedValue: '8'
forRemoval: true
deleteExperienceFieldValues: false
- valueId: 588
definedValue: '9'
forRemoval: true
deleteExperienceFieldValues: false
- valueId: 0
definedValue: 10+
forRemoval: false
deleteExperienceFieldValues: false
isRequired: true
isPrivate: false
isLocked: false
required: true
responses:
'200':
description: 'Success: List of Field Definitions added or updated'
content:
text/plain:
schema:
type: array
items:
$ref: '#/components/schemas/PersonFieldDefinitionResponse'
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PersonFieldDefinitionResponse'
text/json:
schema:
type: array
items:
$ref: '#/components/schemas/PersonFieldDefinitionResponse'
'400':
description: 'Bad Request: Example when trying to set system fields to private that aren''t allowed to be private:
<code>{<br/> "errors": [<br/> {<br/> "errorType": "CannotBeMadePrivate",<br/> "description": "Fields in request cannot be made private.",<br/> "errorCode": null,<br/> "field": "Id",<br/> "values": [<br/> "5"<br/> ],<br/> "innerException": null,<br/> "hResult": -2146233088<br/> }<br/> ],<br/> "title": "One or more validation errors occurred.",<br/> "status": 400,<br/> "instance": "/api/v1/accounts/2/person-fields",<br/> "requestUid": "3dd10d1b-392f-4d5a-b736-50ea1f072342"<br/>}</code>'
'401':
description: Unauthorized
'403':
description: Forbidden
'409':
description: "Conflict - Field definition with name already exists in the account or trying to add or update a field to a system field.\n\n Example when trying to add a field that has the same name as an existing one:\n<code>{<br/> \"errors\": [<br/> {<br/> \"errorType\": \"Duplicate\",<br/> \"description\": \"A name in the request is already in use.\",<br/> \"errorCode\": null,<br/> \"innerException\": null,<br/> \"hResult\": -2146233088<br/> }<br/> ],<br/> \"title\": \"One or more validation errors occurred.\",<br/> \"status\": 409,<br/> \"instance\": \"/api/v1/accounts/2/person-fields\",<br/> \"requestUid\": \"8ba8f060-858b-46d9-b3cc-fa1c391ebc66\"<br/>}</code>"
'422':
description: "Unprocessable Entity - Couldn't remove all defined values from list.\n\n Example when trying to remove a defined value in use from a required list:\n<code>{<br/> \"errors\": [<br/> {<br/> \"errorType\": \"DefinedValueError\",<br/> \"description\": \"23001: Cannot remove field defined value. It is in use for required field(s)\",<br/> \"errorCode\": null,<br/> \"innerException\": null,<br/> \"hResult\": -2146233088<br/> }<br/> ],<br/> \"title\": \"One or more validation errors occurred.\",<br/> \"status\": 422,<br/> \"instance\": \"/api/v1/accounts/2/person-fields\",<br/> \"requestUid\": \"fb8b2dd9-360f-4a81-852c-e5b70cfa5a85\"<br/>}</code>"
delete:
tags:
- PersonFields
summary: Deletes one or more person field definitions in the given account by ids
description: '<strong>NOTE:</strong> system fields cannot be deleted.<br/><strong>Permissions</strong><br/>Account: Write'
operationId: PersonFields_Delete
parameters:
- name: id
in: path
required: true
schema:
type: integer
format: int32
requestBody:
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
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: "Unprocessable Entity: Attempted to remove system field(s)\n\n Example Response:\n<code>{<br/> \"errors\": [<br/> {<br/> \"errorType\": \"NotAllowed\",<br/> \"description\": \"Cannot delete system field(s)\",<br/> \"errorCode\": null,<br/> \"innerException\": null,<br/> \"hResult\": -2146233088<br/> }<br/> ],<br/> \"title\": \"One or more validation errors occurred.\",<br/> \"status\": 422,<br/> \"instance\": \"/api/v1/accounts/2/person-fields\",<br/> \"requestUid\": \"3b3cbfaa-a809-4529-8870-317654a3311e\"<br/>}</code>"
/rp/api/v1/accounts/{id}/person-fields/_reorder:
put:
tags:
- PersonFields
summary: Update the display order of person field definitions for the given account.
description: 'Accepts an array of objects containing fieldId and displayOrder.
System fields cannot be reordered and should not be included in the request.
All custom fields should be included with their new display order values.<br/><strong>Permissions</strong><br/>Account: Write'
operationId: PersonFields_UpdateFieldOrder
parameters:
- name: id
in: path
description: The account ID
required: true
schema:
type: integer
format: int32
requestBody:
description: Array of field order updates
content:
application/json-patch+json:
schema:
minItems: 1
type: array
items:
$ref: '#/components/schemas/FieldOrderRequest'
application/json:
schema:
minItems: 1
type: array
items:
$ref: '#/components/schemas/FieldOrderRequest'
text/json:
schema:
minItems: 1
type: array
items:
$ref: '#/components/schemas/FieldOrderRequest'
application/*+json:
schema:
minItems: 1
type: array
items:
$ref: '#/components/schemas/FieldOrderRequest'
required: true
responses:
'200':
description: 'Success: Field order updated'
content:
text/plain:
schema:
type: array
items:
$ref: '#/components/schemas/PersonFieldDefinitionResponse'
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PersonFieldDefinitionResponse'
text/json:
schema:
type: array
items:
$ref: '#/components/schemas/PersonFieldDefinitionResponse'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
components:
schemas:
FieldDefinedValueRequest:
type: object
properties:
valueId:
type: integer
format: int64
definedValue:
type: string
nullable: true
forRemoval:
type: boolean
deleteExperienceFieldValues:
type: boolean
additionalProperties: false
FieldDefRequest:
type: object
properties:
id:
type: integer
format: int64
example: 1394
name:
type: string
nullable: true
example: Contact Number
type:
enum:
- Boolean
- Date
- Email
- PhoneNumber
- Image
- Text
- LongText
- SingleSelect
- MultiSelect
- Address
- Currency
- Phone
- Integer
- Number
type: string
example: PhoneNumber
definedValues:
type: array
items:
$ref: '#/components/schemas/FieldDefinedValueRequest'
nullable: true
isRequired:
type: boolean
example: false
isPrivate:
type: boolean
example: false
isLocked:
type: boolean
example: false
additionalProperties: false
PersonFieldDefinitionResponse:
type: object
properties:
personType:
type: array
items:
enum:
- Salaried
- Hourly
type: string
nullable: true
example: Salaried
displayOrder:
type: integer
format: int32
nullable: true
example: 1
id:
type: integer
format: int64
example: 1394
name:
type: string
nullable: true
example: Contact Number
type:
enum:
- Boolean
- Date
- Email
- PhoneNumber
- Image
- Text
- LongText
- SingleSelect
- MultiSelect
- Address
- Currency
- Phone
- Integer
- Number
type: string
example: PhoneNumber
definedValues:
type: array
items:
$ref: '#/components/schemas/FieldDefinedValue'
nullable: true
isRequired:
type: boolean
example: false
isSystem:
type: boolean
example: false
isPrivate:
type: boolean
example: false
isFinancials:
type: boolean
example: false
isLocked:
type: boolean
example: false
additionalProperties: false
FieldDefinedValue:
type: object
properties:
valueId:
type: integer
format: int64
example: 13
definedValue:
type: string
nullable: true
example: Defined Value
inUse:
type: array
items:
type: integer
format: int64
nullable: true
additionalProperties: false
FieldOrderRequest:
required:
- displayOrder
- fieldId
type: object
properties:
fieldId:
maximum: 9.223372036854776e+18
minimum: 1
type: integer
description: The field ID to reorder
format: int64
example: 1234
displayOrder:
maximum: 2147483647
minimum: 1
type: integer
description: The new display order position (1-indexed)
format: int32
example: 1
additionalProperties: false
securitySchemes:
Bearer:
type: http
description: Standard Authorization header using the Bearer scheme
scheme: bearer
bearerFormat: JWT