---
title: "Read company positions"
method: POST
path: "/objects/position/search"
tags: ["Workforce Planning"]
---

# Read company positions

`POST /objects/position/search`

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.  <br /><br /> <br /><br /> **<b>Required permissions</b>** <br />    To access the positions, the service user making the call must have the following permissions: <br /> **Features > Workforce planning > Position management > Manage positions**. <br />

## Request body

- GetPositionsRequest
  - `fields` string[], required — 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 <a href="https://apidocs.hibob.com/reference/get_metadata-objects-position">Get all positions fields</a> metadata endpoint. <br /> The array can contain 1 to 50 field IDs. Any invalid number of fields will get a response of 400 HTTP error.<br />
  - `filters` FilterInstruction[], required — An array of filtering conditions.
    - `fieldId` string, required — The field id to filter by.<br /> Supported fields: “/position/status”, "/position/name", "/position/hasOpenRequests" , "position/id".<br />Any other path will get a response of 400 HTTP error.
    - `operator` string, required — Supported operators: “equals”, "notEqual".<br />Any other operator will get a response of 400 HTTP error.
    - `values` string[], required — List of values to compare.<br />Empty list will result in 400 HTTP error.
  - `includeHumanReadable` boolean — Whether to include the additional "humanReadable" entry in the response.

## Response `200`

The positions returned in the response body.

- object[]
  - `/position/fte` object — A numeric field representing the job % allocated to each “chair.”
    - `humanReadable` string
    - `value` number
  - `/position/effectiveDate` object — 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.
    - `humanReadable` string
    - `value` string
  - `/position/endEffectiveDate` object — The date this position's budget stops being effective.
    - `humanReadable` string
    - `value` string
  - `/position/employmentType` object — The position's employment type is an open list (list name is `payrollEmploymentType`) of values taken from your company’s Employment table.
    - `humanReadable` string
    - `value` string
  - `/position/status` object — 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")
    - `humanReadable` string
    - `value` string
  - `/position/actualStartDate` object — The employee's assignment date for this position.
    - `humanReadable` string
    - `value` string
  - `/position/reason` object — Reason for changing or creating this position.
    - `humanReadable` string
    - `value` string
  - `/position/positionType` object — 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`).
    - `humanReadable` string
    - `value` string
  - `/position/filledBy` object — The current assigned employee for this position.
    - `humanReadable` string
    - `value` string
  - `/position/job` object — 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`. <br> **Importnat Note**: This field will be deprecated in the future. We recommend switching to `/position/jobProfile` instead.
    - `humanReadable` string
    - `value` number
  - `/position/jobProfile` object — 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.
    - `humanReadable` string
    - `value` number
  - `/position/recruitmentStatus` object — The position's recruitment status. Possible values and their human-readable values: "open" ("Open"), "onHold" ("On Hold"), "closed" ("Closed")
    - `humanReadable` string
    - `value` string
  - `/position/name` object — 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.
    - `humanReadable` string
    - `value` string
  - `/position/department` object — The position's department. Possible values depend on the values of the department list (list name: `department`).
    - `humanReadable` string
    - `value` string
  - `/position/site` object — The position's site. Possible values depend on the values of the sites list (list name: `site`).
    - `humanReadable` string
    - `value` number
  - `/position/expectedStartDate` object — The expected date this position should be filled.
    - `humanReadable` string
    - `value` string
  - `/position/managerPositionId` object — The manager's position backend-id (a reference to the manager's position in Bob), that allows the creation of a hierarchical org structure.
    - `humanReadable` string
    - `value` number
  - `/position/managerPositionFilledBy` object — The backend-id of the current assigned manager for this position.
    - `humanReadable` string
    - `value` number
  - `/position/hasOpenRequests` object — Whether this position has pending edit requests.
    - `humanReadable` string
    - `value` boolean
  - `/position/modificationDate` object — The date when this position was last modified.
    - `humanReadable` string
    - `value` string
  - `/position/id` object — The id of the position in the backend.
    - `humanReadable` string
    - `value` number
  - `/position/calculatedRecruitmentStatus` object — 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")
    - `humanReadable` string
    - `value` string
  - `/position/calculatedExpectedStartDate` object — The expected start date of the position, calculated by the expected start date of its openings.
    - `humanReadable` string
    - `value` string
  - `/position/calculatedActualStartDate` object — The actual start date of the position, calculated by the actual start date of its openings.
    - `humanReadable` string
    - `value` string
  - `/position/budget` string — 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.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `429` — Rate limit exceeded
- `500` — Internal server error

---

[API](https://skmtc.net/hibob/apis/employee-data-api.md) · [All operations](https://skmtc.net/hibob/apis/employee-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hibob/employee-data-api/versions/0781ebbdda91/schema)