---
updatedAt: 2026-02-16T16:08:06.000Z
---
Fetch the complete documentation index at: https://apidocs.hibob.com/llms.txt. Use this file to discover all available pages before exploring further.
# Position updated webhook
Webhook sent when any position fields are modified in the Workforce Planning module.
Positions can have various attributes such as department, site, employment type, and manager.
The payload includes `fieldUpdatesIds` to indicate which fields were changed.
**Best practice:** Use the event as a notification only, and retrieve the complete position
details using the Read company positions API endpoint.
Use the `fieldUpdatesIds` from the payload to retrieve only the updated field values.
In the right panel, open **Examples** and select **Payload Example** to see a real payload.
# OpenAPI definition
```json
{
"openapi": "3.1.1",
"info": {
"title": "Workforce Planning API",
"description": "Use Public API to access Workforce Planning in Bob",
"license": {
"name": "Proprietary",
"url": "https://apidocs.hibob.com/docs/api-terms-of-use"
},
"contact": {
"name": "Hi Bob, Inc."
},
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.hibob.com/v1",
"description": "Production"
},
{
"url": "https://api.sandbox.hibob.com/v1",
"description": "Sandbox"
}
],
"x-readme": {
"metrics-enabled": false
},
"tags": [
{
"name": "Workforce Planning",
"description": "Operations for managing workforce planning in Bob"
},
{
"name": "Workforce Planning Webhooks",
"description": "Webhook events for workforce planning-related operations"
}
],
"webhooks": {
"positionCreated": {
"post": {
"operationId": "post_webhook_workforce-planning-position-created",
"tags": [
"Workforce Planning Webhooks"
],
"summary": "Position created webhook",
"description": "Webhook sent when a new position is created in the Workforce Planning module.\n\nPositions are a core entity of the Workforce Planning module, enabling you to allocate\nbudgets and assign specific roles to positions for your workforce's current and future needs.\n\n**Best practice:** Use the event as a notification only, and retrieve the complete position\ndetails using the Read company positions API endpoint.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n",
"parameters": [
{
"name": "bob-signature",
"in": "header",
"required": true,
"description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.",
"schema": {
"type": "string",
"example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w=="
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PositionCreatedEvent"
},
"example": {
"companyId": 637323,
"type": "workforcePlanning.position.created",
"triggeredBy": "3418533772247696340",
"triggeredAt": "2024-10-03T09:29:00.831502Z",
"version": "v2",
"data": {
"positionId": 123
}
}
}
}
},
"responses": {
"200": {
"description": "Webhook received successfully"
},
"400": {
"description": "Invalid webhook payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": []
}
},
"positionUpdated": {
"post": {
"operationId": "post_webhook_workforce-planning-position-updated",
"tags": [
"Workforce Planning Webhooks"
],
"summary": "Position updated webhook",
"description": "Webhook sent when any position fields are modified in the Workforce Planning module.\n\nPositions can have various attributes such as department, site, employment type, and manager.\nThe payload includes `fieldUpdatesIds` to indicate which fields were changed.\n\n**Best practice:** Use the event as a notification only, and retrieve the complete position\ndetails using the Read company positions API endpoint.\nUse the `fieldUpdatesIds` from the payload to retrieve only the updated field values.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n",
"parameters": [
{
"name": "bob-signature",
"in": "header",
"required": true,
"description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.",
"schema": {
"type": "string",
"example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w=="
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PositionUpdatedEvent"
},
"example": {
"companyId": 637323,
"type": "workforcePlanning.position.updated",
"triggeredBy": "3418533772247696340",
"triggeredAt": "2024-10-03T09:29:00.831502Z",
"version": "v2",
"data": {
"positionId": 123,
"fieldUpdatesIds": [
{
"id": "/position/status"
}
]
}
}
}
}
},
"responses": {
"200": {
"description": "Webhook received successfully"
},
"400": {
"description": "Invalid webhook payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": []
}
},
"positionOpeningCreated": {
"post": {
"operationId": "post_webhook_workforce-planning-position-opening-created",
"tags": [
"Workforce Planning Webhooks"
],
"summary": "Position opening created webhook",
"description": "Webhook sent when a new position opening is created. Position openings are always linked\nto a Position in Bob.\n\nThey allow organizations to plan multiple hiring scenarios under the same position (e.g.\nmaternity leave replacements or organizational growth) without duplicating positions. Each\nopening can have its recruitment status, expected start date, and opening name.\n\n**Best practice:** Use the event as a notification only, and retrieve the complete position\nopening details using the Read company positions openings API endpoint.\nNote that position opening events don't include the position ID; you can get it by\nretrieving the opening details.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n",
"parameters": [
{
"name": "bob-signature",
"in": "header",
"required": true,
"description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.",
"schema": {
"type": "string",
"example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w=="
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PositionOpeningCreatedEvent"
},
"example": {
"companyId": 637323,
"type": "workforcePlanning.positionOpening.created",
"triggeredBy": "3418533772247696340",
"triggeredAt": "2024-10-03T09:29:00.831502Z",
"version": "v2",
"data": {
"positionOpeningId": 123
}
}
}
}
},
"responses": {
"200": {
"description": "Webhook received successfully"
},
"400": {
"description": "Invalid webhook payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": []
}
},
"positionOpeningUpdated": {
"post": {
"operationId": "post_webhook_workforce-planning-position-opening-updated",
"tags": [
"Workforce Planning Webhooks"
],
"summary": "Position opening updated webhook",
"description": "Webhook sent when position opening fields are modified. Position openings are always linked\nto a Position in Bob.\n\nThe payload includes `fieldUpdatesIds` to indicate which fields were changed.\n\n**Best practice:** Use the event as a notification only, and retrieve the complete position\nopening details using the Read company positions openings API endpoint.\nUse the `fieldUpdatesIds` from the payload to retrieve only the updated field values.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n",
"parameters": [
{
"name": "bob-signature",
"in": "header",
"required": true,
"description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.",
"schema": {
"type": "string",
"example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w=="
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PositionOpeningUpdatedEvent"
},
"example": {
"companyId": 637323,
"type": "workforcePlanning.positionOpening.updated",
"triggeredBy": "3418533772247696340",
"triggeredAt": "2024-10-03T09:29:00.831502Z",
"version": "v2",
"data": {
"positionOpeningId": 123,
"fieldUpdatesIds": [
{
"id": "/positionOpening/status"
}
]
}
}
}
}
},
"responses": {
"200": {
"description": "Webhook received successfully"
},
"400": {
"description": "Invalid webhook payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": []
}
},
"positionOpeningDeleted": {
"post": {
"operationId": "post_webhook_workforce-planning-position-opening-deleted",
"tags": [
"Workforce Planning Webhooks"
],
"summary": "Position opening deleted webhook",
"description": "Webhook sent when a position opening is removed. Position openings are always linked\nto a Position in Bob.\n\n**Best practice:** Use the event as a notification only, and verify the deletion using the\nRead company positions openings API endpoint.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n",
"parameters": [
{
"name": "bob-signature",
"in": "header",
"required": true,
"description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.",
"schema": {
"type": "string",
"example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w=="
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PositionOpeningDeletedEvent"
},
"example": {
"companyId": 637323,
"type": "workforcePlanning.positionOpening.deleted",
"triggeredBy": "3418533772247696340",
"triggeredAt": "2024-10-03T09:29:00.831502Z",
"version": "v2",
"data": {
"positionOpeningId": 123
}
}
}
}
},
"responses": {
"200": {
"description": "Webhook received successfully"
},
"400": {
"description": "Invalid webhook payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": []
}
},
"positionBudgetCreated": {
"post": {
"operationId": "post_webhook_workforce-planning-position-budget-created",
"tags": [
"Workforce Planning Webhooks"
],
"summary": "Position budget created webhook",
"description": "Webhook sent when a new position budget is created. Position budgets are always linked\nto a Position in Bob.\n\nThey allow tracking of the financial allocation for specific roles within the organization.\nBudget attributes include the budget date (when funding starts), currency, base salary, and\nvariable pay. Budgets are available only if you activate the position cost feature in the\nworkforce planning settings.\n\n**Best practice:** Use the event as a notification only, and retrieve the complete position\nbudget details using the Read company positions budgets API endpoint.\nNote that budget events include the position ID, because budget details don't return it.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n",
"parameters": [
{
"name": "bob-signature",
"in": "header",
"required": true,
"description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.",
"schema": {
"type": "string",
"example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w=="
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PositionBudgetCreatedEvent"
},
"example": {
"companyId": 636192,
"type": "workforcePlanning.positionBudget.created",
"triggeredBy": "3332883804594373380",
"triggeredAt": "2025-07-07T14:30:47.831523Z",
"version": "v2",
"data": {
"positionBudgetId": 16649969,
"positionId": 16649970
}
}
}
}
},
"responses": {
"200": {
"description": "Webhook received successfully"
},
"400": {
"description": "Invalid webhook payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": []
}
},
"positionBudgetUpdated": {
"post": {
"operationId": "post_webhook_workforce-planning-position-budget-updated",
"tags": [
"Workforce Planning Webhooks"
],
"summary": "Position budget updated webhook",
"description": "Webhook sent when position budget fields are modified. Position budgets are always linked\nto a Position in Bob.\n\nThey allow tracking of the financial allocation for specific roles within the organization.\nThe payload includes `fieldUpdatesIds` to indicate which fields were changed.\n\n**Best practice:** Use the event as a notification only, and retrieve the complete position\nbudget details using the Read company positions budgets API endpoint.\nUse the `fieldUpdatesIds` from the payload to retrieve only the updated field values. Note\nthat budget events include the position ID, because budget details don't return it.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n",
"parameters": [
{
"name": "bob-signature",
"in": "header",
"required": true,
"description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.",
"schema": {
"type": "string",
"example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w=="
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PositionBudgetUpdatedEvent"
},
"example": {
"companyId": 637323,
"type": "workforcePlanning.positionBudget.updated",
"triggeredBy": "3418533772247696340",
"triggeredAt": "2024-10-03T09:29:00.831502Z",
"version": "v2",
"data": {
"positionBudgetId": 123,
"positionId": 124,
"fieldUpdatesIds": [
{
"id": "/positionBudget/baseSalary"
}
]
}
}
}
}
},
"responses": {
"200": {
"description": "Webhook received successfully"
},
"400": {
"description": "Invalid webhook payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": []
}
}
},
"paths": {
"/metadata/objects/position": {
"get": {
"operationId": "get_metadata-objects-position",
"tags": [
"Workforce Planning"
],
"summary": "Get all positions fields",
"description": "Returns a list of all fields of object type position.
",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ObjectsMetadata"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
}
},
"security": [
{
"Basic": []
},
{
"Bearer": []
}
]
}
},
"/positions/position-openings/metadata": {
"get": {
"operationId": "get_positions-position-openings-metadata",
"tags": [
"Workforce Planning"
],
"summary": "Get all positions openings fields",
"description": "Returns a list of all fields of object type position opening.
",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ObjectsMetadata"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
}
},
"security": [
{
"Basic": []
},
{
"Bearer": []
}
]
}
},
"/positions/position-budget/metadata": {
"get": {
"operationId": "get_positions-position-budget-metadata",
"tags": [
"Workforce Planning"
],
"summary": "Get all position budget fields",
"description": "Returns a list of all fields of object type position budget.
",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ObjectsMetadata"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden. The service user does not have the required permissions.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
}
},
"security": [
{
"Basic": []
},
{
"Bearer": []
}
]
}
},
"/objects/position/search": {
"post": {
"operationId": "post_objects-position-search",
"tags": [
"Workforce Planning"
],
"summary": "Read company positions",
"description": "This endpoint returns a list of company positions filtered by the specified attributes. Note that this endpoint requires body parameters, which is why it is implemented as a POST request.
**Required permissions**
To access the positions, the service user making the call must have the following permissions:
**Features > Workforce planning > Position management > Manage positions**.
",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetPositionsRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "The positions returned in the response body.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PositionEntries"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
}
},
"security": [
{
"Basic": []
},
{
"Bearer": []
}
],
"x-codegen-request-body-name": "body"
}
},
"/positions/position-openings/search": {
"post": {
"operationId": "post_positions-position-openings-search",
"tags": [
"Workforce Planning"
],
"summary": "Read company positions openings",
"description": "This endpoint returns a list of company positions openings filtered by the specified attributes. Note that this endpoint requires body parameters, which is why it is implemented as a POST request.
The required body parameters are:
- **Fields**: Specify the fields you want to retrieve. A list of available fields can be found in the 200 response body detailed below.
- **Filters**: Define the filtering conditions. You can filter by the fields defined in the filter section.
- **Pagination**: This endpoint uses cursor-based pagination to handle large number of table entries. To learn more, see Pagination in Bob's API
**Required permissions**
To access the positions, the service user making the call must have the following permissions:
**Features > Workforce planning > Position management > Manage positions**.
",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetPositionsOpeningsRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "The positions returned in the response body. You can use the fields in the `response body` to see the available fields for filtering the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PositionOpeningsResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
}
},
"security": [
{
"Basic": []
},
{
"Bearer": []
}
],
"x-codegen-request-body-name": "body"
}
},
"/positions/position-budget/search": {
"post": {
"operationId": "post_positions-position-budget-search",
"tags": [
"Workforce Planning"
],
"summary": "Read company positions budgets",
"description": "This endpoint returns a list of company positions budgets filtered by the specified attributes. Note that this endpoint requires body parameters, which is why it is implemented as a POST request.
The required body parameters are:
- **Fields**: Specify the fields you want to retrieve. A list of available fields can be found in the 200 response body detailed below.
- **Filters**: Define the filtering conditions. You can filter by the fields defined in the filter section.
- **Pagination**: This endpoint uses cursor-based pagination to handle large number of table entries. To learn more, see Pagination in Bob's API
**Required permissions**
To access the positions, the service user making the call must have the following permissions:
**Features > Workforce planning > Position management > Manage positions**.
",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetPositionsBudgetsRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "The budgets returned in the response body. You can use the fields in the `response body` to see the available fields for filtering the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PositionBudgetResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
}
},
"security": [
{
"Basic": []
},
{
"Bearer": []
}
],
"x-codegen-request-body-name": "body"
}
},
"/workforce-planning/positions": {
"post": {
"operationId": "post_workforce-planning-positions",
"tags": [
"Workforce Planning"
],
"summary": "Create Position",
"description": "Creates new positions with associated position opening and optional position budget.
**Limitations:**
- You can create up to 10 positions per request.
- If the request includes more than 10 positions, the operation will fail and return an error.
**Notes:**
- When creating a Position, the position opening is mandatory.
- Position budget is optional and will be created only if the service user has the required permission.
- The endpoint will return the ID of the positions and the position opening that were created. To find out the budget ID you should read the position details.
- Currently, you cannot create \"position requests\" that require an approval flow, which are not supported via the API.
- This endpoint requires linking the position to a job profile, and can be used only with Job Catalog 2.0. To retrieve the `jobProfile`, use the Job Catalog API.
- For fields that require reference to a list in Bob (e.g. `department`), use the metadata endpoint to fetch list values.
- For custom fields, use the Examples > Request Example, and copy to an external API client tool to add custom fields to the payload.
\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPositionCreateRequest"
},
"example": {
"items": [
{
"objectType": "position",
"fields": {
"/position/name": {
"value": "P-3632486884"
},
"/position/effectiveDate": {
"value": "2025-04-01"
},
"/position/fte": {
"value": 100
},
"/position/department": {
"value": "Engineering"
},
"/position/site": {
"value": 123
},
"/position/jobProfile": {
"value": 789
},
"/position/positionOpening": {
"objectType": "positionOpening",
"fields": {
"/positionOpening/positionOpeningName": {
"value": "O-1825418083"
},
"/positionOpening/expectedStartDate": {
"value": "2025-04-30"
}
}
},
"/position/positionBudget": {
"objectType": "positionBudget",
"fields": {
"/positionBudget/expectedBaseSalaryCurrencyValue": {
"value": 50000
},
"/positionBudget/salaryPayPeriod": {
"value": "Monthly"
},
"/positionBudget/totalPositionCostCurrencyValue": {
"value": 60000
},
"/positionBudget/currency": {
"value": "USD"
}
}
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "Position request created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PositionWithOpeningResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
}
},
"security": [
{
"Basic": []
},
{
"Bearer": []
}
]
}
},
"/workforce-planning/positions/{positionId}/position-openings": {
"post": {
"operationId": "post_workforce-planning-positions-positionid-position-openings",
"tags": [
"Workforce Planning"
],
"summary": "Create Position Opening",
"description": "Creates a new position opening within a position
**Limitations:**
- You can create up to 10 position openings per request.
- If the request includes more than 10 position openings, the operation will fail and return an error.
**Notes:**
- For fields that require reference to a list in Bob, use the metadata endpoint to fetch list values.
\n",
"parameters": [
{
"name": "positionId",
"in": "path",
"required": true,
"description": "The ID of the position",
"schema": {
"type": "number"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPositionOpeningCreateRequest"
},
"example": {
"items": [
{
"objectType": "positionOpening",
"fields": {
"/positionOpening/positionOpeningName": {
"value": "SWE Opening"
},
"/positionOpening/expectedStartDate": {
"value": "2025-04-30"
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "Position opening created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PositionWithOpeningResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
}
},
"security": [
{
"Basic": []
},
{
"Bearer": []
}
]
}
},
"/workforce-planning/positions/{positionId}": {
"patch": {
"operationId": "patch_workforce-planning-positions-positionid",
"tags": [
"Workforce Planning"
],
"summary": "Update Position",
"description": "Updates an existing position **Notes:**
- Currently, you cannot use approval flows, which are not supported via the API.
- This endpoint requires linking the position to a job profile, and can be used only with Job Catalog 2.0. To retrieve the `jobProfile`, use the Job Catalog API.
- For fields that require reference to a list in Bob (e.g. `department`), use the metadata endpoint to fetch list values.
- For custom fields, use the Examples > Request Example, and copy to an external API client tool to add custom fields to the payload.
\n \n",
"parameters": [
{
"name": "positionId",
"in": "path",
"required": true,
"description": "The ID of the position to update",
"schema": {
"type": "number"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPositionUpdateRequest"
},
"example": {
"items": [
{
"objectType": "position",
"fields": {
"/position/name": {
"value": "Senior Software Engineer"
},
"/position/effectiveDate": {
"value": "2025-04-01"
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "Position updated successfully"
},
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
}
},
"security": [
{
"Basic": []
},
{
"Bearer": []
}
]
}
},
"/workforce-planning/positions/{positionId}/position-openings/{positionOpeningId}": {
"patch": {
"operationId": "patch_workforce-planning-positions-positionid-position-openings-positionopeningid",
"tags": [
"Workforce Planning"
],
"summary": "Update Position Opening",
"description": "Updates a specific position opening within a position **Notes:**
- For fields that require reference to a list in Bob, use the metadata endpoint to fetch list values.
\n",
"parameters": [
{
"name": "positionId",
"in": "path",
"required": true,
"description": "The ID of the position",
"schema": {
"type": "number"
}
},
{
"name": "positionOpeningId",
"in": "path",
"required": true,
"description": "The ID of the position opening to update",
"schema": {
"type": "number"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPositionOpeningUpdateRequest"
},
"example": {
"items": [
{
"objectType": "positionOpening",
"fields": {
"/positionOpening/positionOpeningName": {
"value": "O-1825418083"
},
"/positionOpening/expectedStartDate": {
"value": "2025-04-30"
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "Position opening updated successfully"
},
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
}
},
"security": [
{
"Basic": []
},
{
"Bearer": []
}
]
},
"delete": {
"operationId": "delete_workforce-planning-positions-positionid-position-openings-positionopeningid",
"tags": [
"Workforce Planning"
],
"summary": "Deletes Position Opening",
"description": "Deletes a position opening",
"parameters": [
{
"name": "positionId",
"in": "path",
"required": true,
"description": "The ID of the position",
"schema": {
"type": "number"
}
},
{
"name": "positionOpeningId",
"in": "path",
"required": true,
"description": "The ID of the position opening",
"schema": {
"type": "number"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
}
},
"security": [
{
"Basic": []
},
{
"Bearer": []
}
]
}
},
"/workforce-planning/positions/{positionId}/position-budget": {
"post": {
"operationId": "post_workforce-planning-positions-positionid-position-budget",
"tags": [
"Workforce Planning"
],
"summary": "Create Position Budget",
"description": "Creates a specific position budget within a position **Limitations:**
- You can create up to 1 budget per request.
- If the request includes more than 1 budget, the operation will fail and return an error.
\n",
"parameters": [
{
"name": "positionId",
"in": "path",
"required": true,
"description": "The ID of the position",
"schema": {
"type": "number"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPositionBudgetCreateRequest"
},
"example": {
"items": [
{
"objectType": "positionBudget",
"fields": {
"/positionBudget/expectedBaseSalaryCurrencyValue": {
"value": 50000
},
"/positionBudget/salaryPayPeriod": {
"value": "Monthly"
},
"/positionBudget/totalPositionCostCurrencyValue": {
"value": 60000
},
"/positionBudget/currency": {
"value": "USD"
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "Position budget created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPositionBudgetCreateResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
}
},
"security": [
{
"Basic": []
},
{
"Bearer": []
}
]
}
},
"/workforce-planning/positions/{positionId}/position-budget/{positionBudgetId}": {
"patch": {
"operationId": "patch_workforce-planning-positions-positionid-position-budget-positionbudgetid",
"tags": [
"Workforce Planning"
],
"summary": "Update Position Budget",
"description": "Updates a specific position budget within a position",
"parameters": [
{
"name": "positionId",
"in": "path",
"required": true,
"description": "The ID of the position",
"schema": {
"type": "number"
}
},
{
"name": "positionBudgetId",
"in": "path",
"required": true,
"description": "The ID of the position budget to update",
"schema": {
"type": "number"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPositionBudgetUpdateRequest"
},
"example": {
"items": [
{
"objectType": "positionBudget",
"fields": {
"/positionBudget/expectedBaseSalaryCurrencyValue": {
"value": 50000
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "Position budget updated successfully"
},
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
}
},
"security": [
{
"Basic": []
},
{
"Bearer": []
}
]
}
},
"/workforce-planning/positions/schedule-cancellation": {
"post": {
"operationId": "post_workforce-planning-positions-schedule-cancellation",
"tags": [
"Workforce Planning"
],
"summary": "Schedule Positions Cancellation",
"description": "Schedules the cancellation of one or more positions. This endpoint automatically unassigns any employees connected to the position openings before cancellation.
\nNote:
\n - Cancellation date is optional. If provided, Positions are scheduled to be cancelled at 12:00 AM (midnight) on the specified date. Otherwise, they are cancelled immediately.
\n - If scheduled for a future date, the position and its openings will remain in status \"Cancelled soon\" until cancelled.
\n - After cancellation, the status will change to \"Cancelled\".
\n - If a position is `filled`, the employees assigned to the openings will be automatically unassigned before cancellation.
\n
\nLimitations:
\n - Positions that are already canceled cannot be scheduled for cancellation again.
\n
\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicSchedulePositionsCancellationRequest"
}
}
}
},
"responses": {
"200": {
"description": "Positions cancellation scheduled successfully"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
}
},
"security": [
{
"Basic": []
},
{
"Bearer": []
}
]
}
},
"/workforce-planning/positions/{positionId}/cancel": {
"patch": {
"operationId": "patch_workforce-planning-positions-positionid-cancel",
"tags": [
"Workforce Planning"
],
"summary": "Cancel Position",
"description": "Immediately cancels a position and updates its status to cancelled.
Important: This operation will fail if the position is currently filled (i.e., employees are still assigned to its openings).
To cancel filled positions, use the Schedule Positions Cancellation endpoint, which automatically unassigns employees before cancelling the position.
\n",
"parameters": [
{
"name": "positionId",
"in": "path",
"required": true,
"description": "The ID of the position",
"schema": {
"type": "number"
}
}
],
"responses": {
"200": {
"description": "Position cancelled successfully"
},
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
}
},
"security": [
{
"Basic": []
},
{
"Bearer": []
}
]
}
}
},
"components": {
"schemas": {
"ObjectsMetadata": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the field."
},
"name": {
"type": "string",
"description": "Name of the field."
},
"description": {
"type": "string",
"description": "Description of the field."
},
"fieldType": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The type of the field."
},
"typeData": {
"type": "object",
"properties": {
"listId": {
"type": "string",
"description": "The ID of the list in the /v1/company/named-lists endpoint."
}
}
}
}
},
"jsonPath": {
"type": "object",
"properties": {
"root": {
"type": "string",
"description": "The path to the field json object. The field value and other properties, such as humanReadable value, will be placed inside."
},
"rawData": {
"type": "string",
"description": "The path to the actual field value."
}
}
}
}
},
"GetPositionsRequest": {
"type": "object",
"required": [
"fields",
"filters"
],
"properties": {
"fields": {
"type": "array",
"description": "Array of field IDs to fetch for the positions. A list of the supported field IDs can be found in the '200 response' body detailed below. To find out the field ID of a custom field, use the Get all positions fields metadata endpoint.
The array can contain 1 to 50 field IDs. Any invalid number of fields will get a response of 400 HTTP error.
",
"items": {
"type": "string",
"example": "/position/name"
}
},
"filters": {
"type": "array",
"description": "An array of filtering conditions.",
"items": {
"$ref": "#/components/schemas/FilterInstruction"
}
},
"includeHumanReadable": {
"type": "boolean",
"description": "Whether to include the additional \"humanReadable\" entry in the response.",
"default": false
}
}
},
"FilterInstruction": {
"type": "object",
"required": [
"fieldId",
"operator",
"values"
],
"properties": {
"fieldId": {
"type": "string",
"description": "The field id to filter by.
Supported fields: “/position/status”, \"/position/name\", \"/position/hasOpenRequests\" , \"position/id\".
Any other path will get a response of 400 HTTP error.",
"example": "/position/status"
},
"operator": {
"type": "string",
"example": "equals",
"description": "Supported operators: “equals”, \"notEqual\".
Any other operator will get a response of 400 HTTP error."
},
"values": {
"type": "array",
"description": "List of values to compare.
Empty list will result in 400 HTTP error.",
"items": {
"type": "string",
"example": "vacant"
}
}
}
},
"GetPositionsOpeningsRequest": {
"type": "object",
"required": [
"fields",
"filters"
],
"properties": {
"fields": {
"type": "array",
"description": "Array of field ids to fetch for the positions openings.
Minimum 1 up to 50 fields. Any invalid number of fields will get a response of 400 HTTP error.
You can include only the field ids listed in the '200' response below.",
"items": {
"type": "string",
"example": "/positionOpening/positionOpeningName"
}
},
"filters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PositionOpeningFilterInstruction"
}
},
"includeHumanReadable": {
"type": "boolean",
"description": "Whether to include the additional \"humanReadable\" entry in the response.",
"default": false
},
"pagination": {
"type": "object",
"description": "Optional pagination parameters.",
"properties": {
"limit": {
"description": "The number of results per page. Defaults to 100 if not supplied.",
"type": "number",
"minimum": 1,
"maximum": 100,
"default": 100
},
"cursor": {
"description": "A marker representing the first item on the next page to read. Should not be provided in the first call. To learn more, see Pagination in Bob's API.",
"type": "string",
"default": null
}
}
}
}
},
"PositionOpeningFilterInstruction": {
"type": "object",
"required": [
"fieldId",
"operator",
"values"
],
"properties": {
"fieldId": {
"type": "string",
"description": "The field id to filter by.
Supported fields:
“/positionOpening/id”,
“/positionOpening/status” (possible values: \"vacant\", \"starting\", \"filled\", \"departing\")
\"/positionOpening/positionOpeningName\".
Any other path will get a response of 400 HTTP error.",
"example": "/positionOpening/status"
},
"operator": {
"type": "string",
"example": "equals",
"description": "Supported operators: “equals”, \"notEqual\".
Any other operator will get a response of 400 HTTP error."
},
"values": {
"type": "array",
"description": "List of values to compare.
Empty list will result in 400 HTTP error.",
"items": {
"type": "string",
"example": "vacant"
}
}
}
},
"GetPositionsBudgetsRequest": {
"type": "object",
"required": [
"fields",
"filters"
],
"properties": {
"fields": {
"type": "array",
"description": "Array of field ids to fetch for the positions budgets.
Minimum 1 up to 50 fields. Any invalid number of fields will get a response of 400 HTTP error.
You can include only the field ids listed in the '200' response below.",
"items": {
"type": "string",
"example": "/positionBudget/id"
}
},
"filters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PositionBudgetFilterInstruction"
}
},
"includeHumanReadable": {
"type": "boolean",
"description": "Whether to include the additional \"humanReadable\" entry in the response.",
"default": false
},
"pagination": {
"type": "object",
"description": "Optional pagination parameters.",
"properties": {
"limit": {
"description": "The number of results per page. Defaults to 100 if not supplied.",
"type": "number",
"minimum": 1,
"maximum": 100,
"default": 100
},
"cursor": {
"description": "A marker representing the first item on the next page to read. Should not be provided in the first call. To learn more, see Pagination in Bob's API.",
"type": "string",
"default": null
}
}
}
}
},
"PositionBudgetFilterInstruction": {
"type": "object",
"required": [
"fieldId",
"operator",
"values"
],
"properties": {
"fieldId": {
"type": "string",
"description": "The field id to filter by.
Supported fields:
“/positionBudget/id”
Any other path will get a response of 400 HTTP error.",
"example": "/positionBudget/id"
},
"operator": {
"type": "string",
"example": "equals",
"description": "Supported operators: “equals”, \"notEqual\".
Any other operator will get a response of 400 HTTP error."
},
"values": {
"type": "array",
"description": "List of values to compare.
Empty list will result in 400 HTTP error.",
"items": {
"type": "string",
"example": "12345"
}
}
}
},
"PositionEntries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"/position/fte": {
"type": "object",
"description": "A numeric field representing the job % allocated to each “chair.” \n",
"properties": {
"humanReadable": {
"type": "string",
"example": "5"
},
"value": {
"type": "number",
"example": 5
}
}
},
"/position/effectiveDate": {
"type": "object",
"description": "The date from which this position is budgeted for and should be filled. This can be different from the Start date if the position is filled later than expected. \n",
"properties": {
"humanReadable": {
"type": "string",
"example": "2023-06-23"
},
"value": {
"type": "string",
"example": "2023-06-23"
}
}
},
"/position/endEffectiveDate": {
"type": "object",
"description": "The date this position's budget stops being effective.",
"properties": {
"humanReadable": {
"type": "string",
"example": "2023-06-23"
},
"value": {
"type": "string",
"example": "2023-06-23"
}
}
},
"/position/employmentType": {
"type": "object",
"description": "The position's employment type is an open list (list name is `payrollEmploymentType`) of values taken from your company’s Employment table.",
"properties": {
"humanReadable": {
"type": "string",
"example": "Permanent"
},
"value": {
"type": "string",
"example": "Permanent"
}
}
},
"/position/status": {
"type": "object",
"description": "The position's status. Possible values and their human-readable values: `vacant` (\"Vacant\"), `onHold` (\"On hold\"), `starting` (\"Filled soon\"), `filled` (\"Filled\"), `departing` (\"Vacant soon\"), `cancelledSoon` (\"Cancelled soon\"), `cancelled` (\"Cancelled\")",
"properties": {
"humanReadable": {
"type": "string",
"example": "Vacant"
},
"value": {
"type": "string",
"example": "vacant"
}
}
},
"/position/actualStartDate": {
"type": "object",
"description": "The employee's assignment date for this position.",
"properties": {
"humanReadable": {
"type": "string",
"example": "23/06/2023"
},
"value": {
"type": "string",
"example": "2023-06-23"
}
}
},
"/position/reason": {
"type": "object",
"description": "Reason for changing or creating this position.",
"properties": {
"humanReadable": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"/position/positionType": {
"type": "object",
"description": "The position's type is an open list of values in Bob. The value must be a valid list item. Out-of-the-box values include: `Growth`, `Promotion`, `Replacement` (list name: `positionType`).\n",
"properties": {
"humanReadable": {
"type": "string",
"example": "Growth"
},
"value": {
"type": "string",
"example": "Growth"
}
}
},
"/position/filledBy": {
"type": "object",
"description": "The current assigned employee for this position.",
"properties": {
"humanReadable": {
"type": "string",
"example": "Audrey Darby"
},
"value": {
"type": "string",
"example": "3006749430876471221"
}
}
},
"/position/job": {
"type": "object",
"description": "The ID of the job level associated with this position. If you're using the new Job Catalog 2.0 (either in new installations or after migrating from the old catalog), this field will contain the ID of the job profile and match the value in `/position/jobProfile`.
**Importnat Note**: This field will be deprecated in the future. We recommend switching to `/position/jobProfile` instead.",
"properties": {
"humanReadable": {
"type": "string",
"example": "Sales person Level 1"
},
"value": {
"type": "number",
"example": 128822
}
}
},
"/position/jobProfile": {
"type": "object",
"description": "The ID of the job profile assigned to this position. Job profiles are available only if you're using the new Job Catalog 2.0, either by default or after migrating from the old catalog. Use the Job Catalog API to retrieve job profile details.",
"properties": {
"humanReadable": {
"type": "string",
"example": "Track 1 (1) Product manager (J-7760164138)"
},
"value": {
"type": "number",
"example": 124599
}
}
},
"/position/recruitmentStatus": {
"type": "object",
"description": "The position's recruitment status. Possible values and their human-readable values: \"open\" (\"Open\"), \"onHold\" (\"On Hold\"), \"closed\" (\"Closed\")",
"properties": {
"humanReadable": {
"type": "string",
"example": "Open"
},
"value": {
"type": "string",
"example": "open"
}
}
},
"/position/name": {
"type": "object",
"description": "A unique identifier combined with text, numbers, and other characters of your choosing. When creating a position without passing the name, this will be automatically filled by the system, but it can be changed to reflect the format chosen by your organization. \n",
"properties": {
"humanReadable": {
"type": "string",
"example": "P-2706B"
},
"value": {
"type": "string",
"example": "P-2706B"
}
}
},
"/position/department": {
"type": "object",
"description": "The position's department. Possible values depend on the values of the department list (list name: `department`). ",
"properties": {
"humanReadable": {
"type": "string",
"example": "Accountants"
},
"value": {
"type": "string",
"example": "5887485"
}
}
},
"/position/site": {
"type": "object",
"description": "The position's site. Possible values depend on the values of the sites list (list name: `site`). ",
"properties": {
"humanReadable": {
"type": "string",
"example": "Hong Kong"
},
"value": {
"type": "number",
"example": 2220765
}
}
},
"/position/expectedStartDate": {
"type": "object",
"description": "The expected date this position should be filled.",
"properties": {
"humanReadable": {
"type": "string",
"example": "17/01/2023"
},
"value": {
"type": "string",
"example": "2023-01-17"
}
}
},
"/position/managerPositionId": {
"type": "object",
"description": "The manager's position backend-id (a reference to the manager's position in Bob), that allows the creation of a hierarchical org structure.\n",
"properties": {
"humanReadable": {
"type": "string",
"example": "People and Culture \\ Director (6) Product Manager \\ P-5820313116 · London · TBH"
},
"value": {
"type": "number",
"example": 15826495
}
}
},
"/position/managerPositionFilledBy": {
"type": "object",
"description": "The backend-id of the current assigned manager for this position.",
"properties": {
"humanReadable": {
"type": "string",
"example": "Accountants Sales person Level 1 P-2706B · Hong Kong · Audrey Darby"
},
"value": {
"type": "number",
"example": 257321
}
}
},
"/position/hasOpenRequests": {
"type": "object",
"description": "Whether this position has pending edit requests.",
"properties": {
"humanReadable": {
"type": "string",
"example": "Yes"
},
"value": {
"type": "boolean",
"example": true
}
}
},
"/position/modificationDate": {
"type": "object",
"description": "The date when this position was last modified.",
"properties": {
"humanReadable": {
"type": "string",
"example": "17/01/2023"
},
"value": {
"type": "string",
"example": "2023-01-17"
}
}
},
"/position/id": {
"type": "object",
"description": "The id of the position in the backend.",
"properties": {
"humanReadable": {
"type": "string",
"example": "12345"
},
"value": {
"type": "number",
"example": 12345
}
}
},
"/position/calculatedRecruitmentStatus": {
"type": "object",
"description": "The recruitment status of the position, calculated by the recruitment status of its openings. Possible values and their human-readable values: \"open\" (\"Open\"), \"onHold\" (\"On hold\"), \"closed\" (\"Closed\")",
"properties": {
"humanReadable": {
"type": "string",
"example": "Open"
},
"value": {
"type": "string",
"example": "open"
}
}
},
"/position/calculatedExpectedStartDate": {
"type": "object",
"description": "The expected start date of the position, calculated by the expected start date of its openings.",
"properties": {
"humanReadable": {
"type": "string",
"example": "17/01/2023"
},
"value": {
"type": "string",
"example": "2023-01-17"
}
}
},
"/position/calculatedActualStartDate": {
"type": "object",
"description": "The actual start date of the position, calculated by the actual start date of its openings.",
"properties": {
"humanReadable": {
"type": "string",
"example": "17/01/2023"
},
"value": {
"type": "string",
"example": "2023-01-17"
}
}
},
"/position/budget": {
"type": "string",
"description": "The backend identifier of the budget (cost) associated with this position. This field is included in the response only for positions with a defined budget. If no budget is defined, this field will not be returned. Use the budget ID to retrieve the budget amount and details through the 'Get Position Budgets' endpoint.",
"properties": {
"humanReadable": {
"type": "string",
"example": "1234"
},
"value": {
"type": "number",
"example": 1234
}
}
}
}
}
},
"PositionOpeningsResponse": {
"type": "object",
"properties": {
"positionOpeningEntries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PositionOpeningEntries"
}
},
"response_metadata": {
"type": "object",
"properties": {
"next_cursor": {
"type": "string",
"description": "Cursor for the next call, or null if there are no more results."
}
}
}
}
},
"PositionOpeningEntries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"/positionOpening/updateEffectiveDate": {
"type": "object",
"description": "The date this position opening becomes effective.",
"properties": {
"humanReadable": {
"type": "string",
"example": "23/06/2023"
},
"value": {
"type": "string",
"example": "2023-06-23"
}
}
},
"/positionOpening/status": {
"type": "object",
"description": "The position opening's status. Possible values and their human-readable values: \"vacant\" (\"Vacant\"), \"starting\" (\"Filled soon\"), \"filled\" (\"Filled\"), \"departing\" (\"Vacant soon\")",
"properties": {
"humanReadable": {
"type": "string",
"example": "Vacant"
},
"value": {
"type": "string",
"example": "vacant"
}
}
},
"/positionOpening/actualStartDate": {
"type": "object",
"description": "The employee's assignment date for this position opening.",
"properties": {
"humanReadable": {
"type": "string",
"example": "23/06/2023"
},
"value": {
"type": "string",
"example": "2023-06-23"
}
}
},
"/positionOpening/filledBy": {
"type": "object",
"description": "The current assigned employee for this position opening.",
"properties": {
"humanReadable": {
"type": "string",
"example": "Audrey Darby"
},
"value": {
"type": "string",
"example": "3006749430876471221"
}
}
},
"/positionOpening/recruitmentStatus": {
"type": "object",
"description": "The recruitment status of the position opening. Possible values and their human-readable values: \"open\" (\"Open\"), \"onHold\" (\"On hold\"), \"closed\" (\"Closed\")",
"properties": {
"humanReadable": {
"type": "string",
"example": "Open"
},
"value": {
"type": "string",
"example": "open"
}
}
},
"/positionOpening/positionOpeningName": {
"type": "object",
"description": "The unique ID of this position opening.",
"properties": {
"humanReadable": {
"type": "string",
"example": "O-2706B"
},
"value": {
"type": "string",
"example": "O-2706B"
}
}
},
"/positionOpening/expectedStartDate": {
"type": "object",
"description": "The expected date this position opening should be filled.",
"properties": {
"humanReadable": {
"type": "string",
"example": "17/01/2023"
},
"value": {
"type": "string",
"example": "2023-01-17"
}
}
},
"/positionOpening/positionId": {
"type": "object",
"description": "The unique ID of the position which the position opening is associate with.",
"properties": {
"humanReadable": {
"type": "string",
"example": "Creative job 1 Level 1 P-1234567 · New York (Demo) · TBH"
},
"value": {
"type": "number",
"example": 1234
}
}
}
}
}
},
"PositionBudgetResponse": {
"type": "object",
"properties": {
"positionBudgetEntries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PositionBudgetEntries"
}
},
"response_metadata": {
"type": "object",
"properties": {
"next_cursor": {
"type": "string",
"description": "Cursor for the next call, or null if there are no more results."
}
}
}
}
},
"PositionBudgetEntries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"/positionBudget/expectedBaseSalaryCurrencyValue": {
"type": "object",
"description": "The expected base salary related to this budget.",
"properties": {
"humanReadable": {
"type": "string",
"example": "12345$"
},
"value": {
"type": "object",
"properties": {
"value": {
"type": "number",
"example": 12345
},
"currency": {
"type": "string",
"example": "USD"
}
}
}
}
},
"/positionBudget/expectedVariablePayCurrencyValue": {
"type": "object",
"description": "The expected variable pay related to this budget.",
"properties": {
"humanReadable": {
"type": "string",
"example": "12345$"
},
"value": {
"type": "object",
"properties": {
"value": {
"type": "number",
"example": 12345
},
"currency": {
"type": "string",
"example": "USD"
}
}
}
}
},
"/positionBudget/salaryPayPeriod": {
"type": "object",
"description": "The salary pay period related to this budget. Possible values - Annual, Annual 13, Annual 14, Hourly, Daily, Weekly, Monthly, Monthly 13, Monthly 14, Quarterly",
"properties": {
"humanReadable": {
"type": "string",
"example": "Weekly"
},
"value": {
"type": "string",
"example": "Weekly"
}
}
},
"/positionBudget/variablePayPeriod": {
"type": "object",
"description": "The variable pay period related to this budget. Possible values - Annual, Annual 13, Annual 14, Hourly, Daily, Weekly, Monthly, Monthly 13, Monthly 14, Quarterly",
"properties": {
"humanReadable": {
"type": "string",
"example": "Weekly"
},
"value": {
"type": "string",
"example": "Weekly"
}
}
},
"/positionBudget/currency": {
"type": "object",
"description": "The currency defined to this budget.",
"properties": {
"humanReadable": {
"type": "string",
"example": "$"
},
"value": {
"type": "string",
"example": "USD"
}
}
},
"/positionBudget/totalPositionCostCurrencyValue": {
"type": "object",
"description": "The total position cost related to this budget.",
"properties": {
"humanReadable": {
"type": "string",
"example": "12345$"
},
"value": {
"type": "object",
"properties": {
"value": {
"type": "number",
"example": 12345
},
"currency": {
"type": "string",
"example": "USD"
}
}
}
}
},
"/positionBudget/convertedTotalCostCurrencyValue": {
"type": "object",
"description": "The total position cost converted to company currency related to this budget.",
"properties": {
"humanReadable": {
"type": "string",
"example": "12345$"
},
"value": {
"type": "object",
"properties": {
"value": {
"type": "number",
"example": 12345
},
"currency": {
"type": "string",
"example": "USD"
}
}
}
}
},
"/positionBudget/proRatedCostCurrencyValue": {
"type": "object",
"description": "A calculated field that represents the total cost of a position, converted to the company’s base currency. The value is pro rated based on the portion of time within the current fiscal year when the position is active, using the position's effectiveDate and optional endEffectiveDate.\n",
"properties": {
"humanReadable": {
"type": "string",
"example": "12345$"
},
"value": {
"type": "object",
"properties": {
"value": {
"type": "number",
"example": 12345
},
"currency": {
"type": "string",
"example": "USD"
}
}
}
}
},
"/positionBudget/updateEffectiveDate": {
"type": "object",
"description": "The date this budget becomes effective.",
"properties": {
"humanReadable": {
"type": "string",
"example": "23/06/2023"
},
"value": {
"type": "string",
"example": "23/06/2023"
}
}
},
"/positionBudget/id": {
"type": "object",
"description": "The id of the budget.",
"properties": {
"humanReadable": {
"type": "string",
"example": "12345"
},
"value": {
"type": "number",
"example": 12345
}
}
}
}
}
},
"PublicPositionCreateRequest": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"maxItems": 10,
"items": {
"$ref": "#/components/schemas/PublicPositionCreateItem"
}
}
}
},
"PublicPositionOpeningCreateRequest": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"maxItems": 10,
"items": {
"$ref": "#/components/schemas/PublicPositionOpeningCreateItem"
}
}
}
},
"PublicPositionBudgetCreateRequest": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"maxItems": 1,
"items": {
"$ref": "#/components/schemas/PublicPositionBudgetCreateItem"
}
}
}
},
"PublicPositionUpdateRequest": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"maxItems": 1,
"items": {
"$ref": "#/components/schemas/PublicPositionUpdateItem"
}
}
}
},
"PublicPositionOpeningUpdateRequest": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"maxItems": 1,
"items": {
"$ref": "#/components/schemas/PublicPositionOpeningUpdateItem"
}
}
}
},
"PublicPositionBudgetUpdateRequest": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"maxItems": 1,
"items": {
"$ref": "#/components/schemas/PublicPositionBudgetUpdateItem"
}
}
}
},
"PublicPositionCreateItem": {
"type": "object",
"required": [
"objectType",
"fields"
],
"properties": {
"objectType": {
"type": "string",
"enum": [
"position"
]
},
"fields": {
"$ref": "#/components/schemas/PublicPositionCreate"
}
}
},
"PublicPositionOpeningCreateItem": {
"type": "object",
"required": [
"objectType",
"fields"
],
"properties": {
"objectType": {
"type": "string",
"enum": [
"positionOpening"
]
},
"fields": {
"$ref": "#/components/schemas/PublicPositionOpeningCreate"
}
}
},
"PublicPositionBudgetCreateItem": {
"type": "object",
"required": [
"objectType",
"fields"
],
"properties": {
"objectType": {
"type": "string",
"enum": [
"positionBudget"
]
},
"fields": {
"$ref": "#/components/schemas/PublicPositionBudgetCreate"
}
}
},
"PublicPositionUpdateItem": {
"type": "object",
"required": [
"objectType",
"fields"
],
"properties": {
"objectType": {
"type": "string",
"enum": [
"position"
]
},
"fields": {
"$ref": "#/components/schemas/PublicPositionUpdate"
}
}
},
"PublicPositionOpeningUpdateItem": {
"type": "object",
"required": [
"objectType",
"fields"
],
"properties": {
"objectType": {
"type": "string",
"enum": [
"positionOpening"
]
},
"fields": {
"$ref": "#/components/schemas/PublicPositionOpeningUpdate"
}
}
},
"PublicPositionBudgetUpdateItem": {
"type": "object",
"required": [
"objectType",
"fields"
],
"properties": {
"objectType": {
"type": "string",
"enum": [
"positionBudget"
]
},
"fields": {
"$ref": "#/components/schemas/PublicPositionBudgetUpdate"
}
}
},
"PublicPositionCreate": {
"type": "object",
"required": [
"/position/effectiveDate",
"/position/fte",
"/position/department",
"/position/site",
"/position/jobProfile",
"/position/positionOpening"
],
"properties": {
"/position/name": {
"type": "object",
"description": "A unique identifier combined with text, numbers, and other characters of your choosing. When creating a position without passing the name, this will be automatically filled by the system, but it can be changed to reflect the format chosen by your organization. \n",
"properties": {
"value": {
"type": [
"string",
"null"
]
}
}
},
"/position/effectiveDate": {
"type": "object",
"description": "The date from which this position is budgeted for and should be filled. This can be different from the Start date if the position is filled later than expected. This is a mandatory field.\n",
"required": [
"value"
],
"properties": {
"value": {
"type": "string",
"format": "date",
"example": "2025-04-01"
}
}
},
"/position/managerPositionId": {
"type": "object",
"description": "The manager's position backend-id (a reference to the manager's position in Bob), that allows the creation of a hierarchical org structure.\n",
"properties": {
"value": {
"type": [
"number",
"null"
]
}
}
},
"/position/positionType": {
"type": "object",
"description": "The position's type is an open list of values in Bob. The value must be a valid list item. Out-of-the-box values include: `Growth`, `Promotion`, `Replacement` (list name: `positionType`).\n",
"properties": {
"value": {
"type": [
"string",
"null"
]
}
}
},
"/position/fte": {
"description": "A numeric field representing the job % allocated to each “chair.” This is a mandatory field.\n",
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number"
}
}
},
"/position/employmentType": {
"type": "object",
"description": "The position's employment type is an open list (list name: `payrollEmploymentType`) of values taken from your company’s Employment table. Out-of-the-box values: `Permanent`, `Temporary`, `Apprentice`, `Contractor`, `Non-guaranteed`.",
"properties": {
"value": {
"type": [
"string",
"null"
]
}
}
},
"/position/department": {
"type": "object",
"description": "The position's department. Possible values are list-items from the department list in Bob (list name: `department`). ",
"required": [
"value"
],
"properties": {
"value": {
"type": "string"
}
}
},
"/position/site": {
"type": "object",
"description": "The position's site. Possible values are list-items from the sites list in Bob (list name: `site`). ",
"required": [
"value"
],
"properties": {
"value": {
"type": "number"
}
}
},
"/position/jobProfile": {
"type": "object",
"description": "The backend ID of the job profile assigned to this position. Use the Job Catalog API to retrieve job profiles and their IDs.
**Note**: You must use **Job Catalog 2.0** in order to have access to job profiles. ",
"required": [
"value"
],
"properties": {
"value": {
"type": "number"
}
}
},
"/position/reason": {
"type": "object",
"description": "Reason for changing or creating this position.",
"properties": {
"value": {
"type": [
"string",
"null"
]
}
}
},
"/position/positionOpening": {
"$ref": "#/components/schemas/PublicPositionOpeningCreateItem"
},
"/position/positionBudget": {
"$ref": "#/components/schemas/PublicPositionBudgetCreateItem"
}
}
},
"PublicPositionOpeningCreate": {
"type": "object",
"required": [
"/positionOpening/expectedStartDate"
],
"properties": {
"/positionOpening/positionOpeningName": {
"type": "object",
"description": "A unique identifier for each opening within a position. Using the API you can provide the name that reflects the format chosen by your organization. If not passed, the system will automatically fill this out.\n",
"properties": {
"value": {
"type": [
"string",
"null"
]
}
}
},
"/positionOpening/expectedStartDate": {
"type": "object",
"description": "The expected start date is the realistic forecast of the date on which the position should be filled. This is a mandatory field.\n",
"required": [
"value"
],
"properties": {
"value": {
"type": "string",
"format": "date",
"example": "2025-04-01"
}
}
},
"/positionOpening/recruitmentStatus": {
"type": "object",
"description": "A list of possible recruitment status for the position opening. Out-of-the-box values include: `open`, `onHold`, and `closed` (list name: `recruitmentStatus`).",
"properties": {
"value": {
"type": [
"string",
"null"
]
}
}
}
}
},
"PublicPositionBudgetCreate": {
"type": "object",
"required": [
"/positionBudget/salaryPayPeriod",
"/positionBudget/currency"
],
"properties": {
"/positionBudget/expectedBaseSalaryCurrencyValue": {
"type": "object",
"description": "The expected base salary is the fixed amount of money allocated as regular compensation for a position, not including bonuses or other variable pay.\n",
"properties": {
"value": {
"type": [
"number",
"null"
]
}
}
},
"/positionBudget/salaryPayPeriod": {
"type": "object",
"description": "Specifies the frequency and timing of salary payments for this budget, such as monthly or weekly. The possible values are a list in Bob (list name: `payPeriod`)\n",
"required": [
"value"
],
"properties": {
"value": {
"type": "string",
"enum": [
"Annual",
"Annual 13",
"Annual 14",
"Hourly",
"Daily",
"Weekly",
"Monthly",
"Monthly 13",
"Monthly 14",
"Quarterly"
]
}
}
},
"/positionBudget/totalPositionCostCurrencyValue": {
"type": "object",
"description": "The total position cost related to this budget.\n",
"properties": {
"value": {
"type": [
"number",
"null"
]
}
}
},
"/positionBudget/currency": {
"type": "object",
"required": [
"value"
],
"description": "The currency of the position budget. To obtain the available currency codes, call the Get all company lists Metadata API with `currency` in the listname path parameter.",
"properties": {
"value": {
"type": "string"
}
}
},
"/positionBudget/variablePayPeriod": {
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "string",
"enum": [
"Quarterly",
"Monthly",
"Half-Yearly",
"Annual"
]
}
}
},
"/positionBudget/expectedVariablePayCurrencyValue": {
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number"
}
}
}
}
},
"PublicPositionUpdate": {
"type": "object",
"properties": {
"/position/name": {
"type": "object",
"description": "A unique identifier combined with text, numbers, and other characters of your choosing. When creating a position without passing the name, this will be automatically filled by the system, but it can be changed to reflect the format chosen by your organization. \n",
"properties": {
"value": {
"type": [
"string",
"null"
]
}
}
},
"/position/effectiveDate": {
"type": "object",
"description": "The date from which this position is budgeted for and should be filled. This can be different from the Start date if the position is filled later than expected. \n",
"properties": {
"value": {
"type": "string",
"format": "date",
"example": "2025-04-01"
}
}
},
"/position/managerPositionId": {
"type": "object",
"description": "The manager's position backend-id (a reference to the manager's position in Bob), that allows the creation of a hierarchical org structure.\n",
"properties": {
"value": {
"type": "number"
}
}
},
"/position/positionType": {
"type": "object",
"description": "The position's type is an open list of values in Bob. The value must be a valid list item. Out-of-the-box values include: `Growth`, `Promotion`, `Replacement` (list name: `positionType`).\n",
"properties": {
"value": {
"type": "string"
}
}
},
"/position/fte": {
"type": "object",
"description": "A numeric field representing the job % allocated to each “chair.” \n",
"properties": {
"value": {
"type": "number"
}
}
},
"/position/employmentType": {
"type": "object",
"description": "The position's employment type is an open list (list name: `payrollEmploymentType`) of values taken from your company’s Employment table. Out-of-the-box values: `Permanent`, `Temporary`, `Apprentice`, `Contractor`, `Non-guaranteed`.",
"properties": {
"value": {
"type": "string"
}
}
},
"/position/department": {
"type": "object",
"description": "The position's department. Possible values depend on the values of the department list (list name: `department`). ",
"properties": {
"value": {
"type": "string"
}
}
},
"/position/site": {
"type": "object",
"description": "The position's site. Possible values are list-items from the sites list in Bob (list name: `site`). ",
"properties": {
"value": {
"type": "number"
}
}
},
"/position/jobProfile": {
"type": "object",
"description": "The backend ID of the job profile assigned to this position. Use the Job Catalog API to retrieve job profiles and their IDs.
\n **Note**: You must use **Job Catalog 2.0** in order to have access to job profiles. ",
"properties": {
"value": {
"type": "number"
}
}
},
"/position/reason": {
"type": "object",
"description": "Reason for changing or creating this position.",
"properties": {
"value": {
"type": "string"
}
}
}
}
},
"PublicPositionOpeningUpdate": {
"type": "object",
"properties": {
"/positionOpening/positionOpeningName": {
"type": "object",
"description": "A unique identifier for each opening within a position. Using the API you can provide the name that reflects the format chosen by your organization. If not passed, the system will automatically fill this out.\n",
"properties": {
"value": {
"type": [
"string",
"null"
]
}
}
},
"/positionOpening/expectedStartDate": {
"type": "object",
"description": "The expected start date is the realistic forecast of the date on which the position should be filled. This is a mandatory field.\n",
"properties": {
"value": {
"type": "string",
"format": "date",
"example": "2025-04-01"
}
}
},
"/positionOpening/recruitmentStatus": {
"type": "object",
"description": "A list of possible recruitment status for the position opening. Out-of-the-box values include: `open`, `onHold`, and `closed` (list name: `recruitmentStatus`).",
"properties": {
"value": {
"type": [
"string",
"null"
]
}
}
}
}
},
"PublicPositionBudgetUpdate": {
"type": "object",
"properties": {
"/positionBudget/expectedBaseSalaryCurrencyValue": {
"type": "object",
"properties": {
"value": {
"type": "number"
}
}
},
"/positionBudget/salaryPayPeriod": {
"type": "object",
"properties": {
"value": {
"type": "string",
"enum": [
"Annual",
"Annual 13",
"Annual 14",
"Hourly",
"Daily",
"Weekly",
"Monthly",
"Monthly 13",
"Monthly 14",
"Quarterly"
]
}
}
},
"/positionBudget/totalPositionCostCurrencyValue": {
"type": "object",
"properties": {
"value": {
"type": "number"
}
}
},
"/positionBudget/currency": {
"type": "object",
"description": "The currency of the position budget. To obtain the available currency codes, call the Get all company lists Metadata API with `currency` in the listname path parameter.",
"properties": {
"value": {
"type": "string"
}
}
},
"/positionBudget/variablePayPeriod": {
"type": "object",
"properties": {
"value": {
"type": "string",
"enum": [
"Quarterly",
"Monthly",
"Half-Yearly",
"Annual"
]
}
}
},
"/positionBudget/expectedVariablePayCurrencyValue": {
"type": "object",
"properties": {
"value": {
"type": "number"
}
}
}
}
},
"PositionWithOpeningResponse": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The ID of the created position"
},
"positionOpeningId": {
"type": "number",
"description": "The ID of the created position opening"
}
}
},
"PublicPositionBudgetCreateResponse": {
"type": "object",
"properties": {
"positionBudgetId": {
"type": "number",
"description": "The ID of the created budget"
}
}
},
"PublicSchedulePositionsCancellationRequest": {
"type": "object",
"required": [
"positionIds"
],
"properties": {
"positionIds": {
"type": "array",
"description": "A list of position IDs to be cancelled. To retrieve position IDs, use the Position Search endpoint.",
"items": {
"type": "number"
}
},
"cancellationDate": {
"type": [
"string",
"null"
],
"format": "date",
"description": "The date on which the positions should be cancelled (optional). If provided, cancellation will occur at 12:00 AM (midnight) on the specified date. Otherwise, the date defaults to today and the cancellation occurs immediately. In this case, there is no \"Cancelled Soon\" status; the position goes straight to \"Cancelled\"."
}
}
},
"ApiErrorResponse": {
"type": "object",
"description": "Standard API error response body",
"properties": {
"key": {
"type": "string",
"description": "The unique identifier of the error."
},
"error": {
"type": "string",
"description": "A human readable error message."
}
}
},
"Error": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "The unique identifier of the error."
},
"error": {
"type": "string",
"description": "A human readable error message."
}
}
},
"WebhookEvent": {
"type": "object",
"description": "Base webhook event structure containing common webhook properties",
"properties": {
"companyId": {
"type": "number",
"description": "The company ID"
},
"type": {
"type": "string",
"description": "The event type (e.g., workforcePlanning.position.created)"
},
"triggeredBy": {
"type": "string",
"description": "The backend-id of the employee that triggered the event or 'system' for events triggered automatically by the system"
},
"triggeredAt": {
"type": "string",
"format": "date-time",
"description": "The timestamp when the event occurred"
},
"version": {
"type": "string",
"description": "The webhook version"
},
"data": {
"type": "object",
"description": "Contains the actual data and differs for each event type"
}
},
"required": [
"companyId",
"type",
"triggeredBy",
"triggeredAt",
"version",
"data"
]
},
"FieldId": {
"type": "object",
"description": "Field ID structure for field updates",
"properties": {
"id": {
"type": "string",
"description": "The field path (e.g., /position/status)"
}
},
"required": [
"id"
]
},
"PositionCreatedEvent": {
"allOf": [
{
"$ref": "#/components/schemas/WebhookEvent"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"workforcePlanning.position.created"
],
"description": "The event type for position creation"
},
"data": {
"type": "object",
"properties": {
"positionId": {
"type": "number",
"description": "The ID of the created position"
}
},
"required": [
"positionId"
]
}
},
"description": "Webhook sent when a new position is created in the Workforce Planning module."
}
]
},
"PositionUpdatedEvent": {
"allOf": [
{
"$ref": "#/components/schemas/WebhookEvent"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"workforcePlanning.position.updated"
],
"description": "The event type for position update"
},
"data": {
"type": "object",
"properties": {
"positionId": {
"type": "number",
"description": "The ID of the updated position"
},
"fieldUpdatesIds": {
"type": "array",
"description": "List of field paths that were updated",
"items": {
"$ref": "#/components/schemas/FieldId"
}
}
},
"required": [
"positionId",
"fieldUpdatesIds"
]
}
},
"description": "Webhook sent when any position fields are modified in the Workforce Planning module."
}
]
},
"PositionOpeningCreatedEvent": {
"allOf": [
{
"$ref": "#/components/schemas/WebhookEvent"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"workforcePlanning.positionOpening.created"
],
"description": "The event type for position opening creation"
},
"data": {
"type": "object",
"properties": {
"positionOpeningId": {
"type": "number",
"description": "The ID of the created position opening"
}
},
"required": [
"positionOpeningId"
]
}
},
"description": "Webhook sent when a new position opening is created."
}
]
},
"PositionOpeningUpdatedEvent": {
"allOf": [
{
"$ref": "#/components/schemas/WebhookEvent"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"workforcePlanning.positionOpening.updated"
],
"description": "The event type for position opening update"
},
"data": {
"type": "object",
"properties": {
"positionOpeningId": {
"type": "number",
"description": "The ID of the updated position opening"
},
"fieldUpdatesIds": {
"type": "array",
"description": "List of field paths that were updated",
"items": {
"$ref": "#/components/schemas/FieldId"
}
}
},
"required": [
"positionOpeningId",
"fieldUpdatesIds"
]
}
},
"description": "Webhook sent when position opening fields are modified."
}
]
},
"PositionOpeningDeletedEvent": {
"allOf": [
{
"$ref": "#/components/schemas/WebhookEvent"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"workforcePlanning.positionOpening.deleted"
],
"description": "The event type for position opening deletion"
},
"data": {
"type": "object",
"properties": {
"positionOpeningId": {
"type": "number",
"description": "The ID of the deleted position opening"
}
},
"required": [
"positionOpeningId"
]
}
},
"description": "Webhook sent when a position opening is removed."
}
]
},
"PositionBudgetCreatedEvent": {
"allOf": [
{
"$ref": "#/components/schemas/WebhookEvent"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"workforcePlanning.positionBudget.created"
],
"description": "The event type for position budget creation"
},
"data": {
"type": "object",
"properties": {
"positionBudgetId": {
"type": "number",
"description": "The ID of the created position budget"
},
"positionId": {
"type": "number",
"description": "The ID of the position this budget is linked to"
}
},
"required": [
"positionBudgetId",
"positionId"
]
}
},
"description": "Webhook sent when a new position budget is created. The event payload includes the position ID that this budget is linked to."
}
]
},
"PositionBudgetUpdatedEvent": {
"allOf": [
{
"$ref": "#/components/schemas/WebhookEvent"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"workforcePlanning.positionBudget.updated"
],
"description": "The event type for position budget update"
},
"data": {
"type": "object",
"properties": {
"positionBudgetId": {
"type": "number",
"description": "The ID of the updated position budget"
},
"positionId": {
"type": "number",
"description": "The ID of the position this budget is linked to"
},
"fieldUpdatesIds": {
"type": "array",
"description": "List of field paths that were updated",
"items": {
"$ref": "#/components/schemas/FieldId"
}
}
},
"required": [
"positionBudgetId",
"positionId",
"fieldUpdatesIds"
]
}
},
"description": "Webhook sent when position budget fields are modified. The event payload includes the position ID that this budget is linked to."
}
]
}
},
"securitySchemes": {
"Basic": {
"type": "http",
"scheme": "basic"
},
"Bearer": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "OAuth 2.0",
"description": "OAuth 2.0 authentication using an Access Token is available for registered partners only. Try It! does not support the full HiBob OAuth flow. You can follow these steps to complete the OAuth 2.0 flow in Postman and then paste the token here."
}
}
}
}
```