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

# Read company positions openings

`POST /positions/position-openings/search`

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.  <br /><br /> The required body parameters are: <br /> - **Fields**: Specify the fields you want to retrieve. A list of available fields can be found in the 200 response body detailed below.<br /> - **Filters**: Define the filtering conditions. You can filter by the fields defined in the filter section.<br /> - **Pagination**: This endpoint uses cursor-based pagination to handle large number of table entries. To learn more, see <a href="https://apidocs.hibob.com/docs/pagination" target=”_blank”>Pagination in Bob's API</a><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

- GetPositionsOpeningsRequest
  - `fields` string[], required — Array of field ids to fetch for the positions openings.<br /> Minimum 1 up to 50 fields. Any invalid number of fields will get a response of 400 HTTP error.<br /> You can include only the field ids listed in the '200' response below.
  - `filters` PositionOpeningFilterInstruction[], required
    - `fieldId` string, required — The field id to filter by.<br /> Supported fields: <br>“/positionOpening/id”, <br>“/positionOpening/status” (possible values: "vacant", "starting", "filled", "departing") <br />"/positionOpening/positionOpeningName". <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.
  - `pagination` object — Optional pagination parameters.
    - `limit` number — The number of results per page. Defaults to 100 if not supplied.
    - `cursor` string — A marker representing the first item on the next page to read. Should not be provided in the first call. To learn more, see <a href="https://apidocs.hibob.com/docs/pagination" target=”_blank”>Pagination in Bob's API</a>.

## Response `200`

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.

- PositionOpeningsResponse
  - `positionOpeningEntries` PositionOpeningEntries[]
    - object[]
      - `/positionOpening/updateEffectiveDate` object — The date this position opening becomes effective.
        - `humanReadable` string
        - `value` string
      - `/positionOpening/status` object — The position opening's status. Possible values and their human-readable values: "vacant" ("Vacant"), "starting" ("Filled soon"), "filled" ("Filled"), "departing" ("Vacant soon")
        - `humanReadable` string
        - `value` string
      - `/positionOpening/actualStartDate` object — The employee's assignment date for this position opening.
        - `humanReadable` string
        - `value` string
      - `/positionOpening/filledBy` object — The current assigned employee for this position opening.
        - `humanReadable` string
        - `value` string
      - `/positionOpening/recruitmentStatus` object — The recruitment status of the position opening. Possible values and their human-readable values: "open" ("Open"), "onHold" ("On hold"), "closed" ("Closed")
        - `humanReadable` string
        - `value` string
      - `/positionOpening/positionOpeningName` object — The unique ID of this position opening.
        - `humanReadable` string
        - `value` string
      - `/positionOpening/expectedStartDate` object — The expected date this position opening should be filled.
        - `humanReadable` string
        - `value` string
      - `/positionOpening/positionId` object — The unique ID of the position which the position opening is associate with.
        - `humanReadable` string
        - `value` number
  - `response_metadata` object
    - `next_cursor` string — Cursor for the next call, or null if there are no more results.

## 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)