---
title: "Get staffing entities"
method: GET
path: "/hris/staffing-entities"
tags: ["Unified HRIS API"]
---

# Get staffing entities

`GET /hris/staffing-entities`

Retrieve all staffing entities.

Retrieve all staffing entities (positions, requisitions, and jobs) from the HRIS system.

Many enterprise HRIS platforms distinguish between **positions**, **requisitions**, and **jobs** — three related but different concepts used to manage headcount and hiring. Not every HRIS uses all three, and naming varies across systems, but here is a general overview:

- **Position**: A slot in the organizational structure that represents a role to be filled (or already filled) by one or more employees. Positions typically carry metadata like department, location, cost center, and reporting line. Think of it as "a chair at a desk" — it exists whether someone is sitting in it or not.
- **Requisition**: A formal request to fill a position. When a manager wants to hire for an open position, they usually create a requisition that goes through an approval workflow. Requisitions are time-bound and tied to a specific hiring need. In Kombo's data model, a requisition's `parent_id` points to the position it was opened for.
- **Job**: Some systems use "job" as a more generic or lightweight alternative to a requisition. Jobs often represent an ongoing, unlimited hiring need (e.g., a company that is always hiring for "Software Engineer") rather than a one-off backfill. This is reflected in the `OPEN_UNLIMITED` status.

You can use the `model_types` filter to retrieve only the type(s) relevant to your use case. Each record's `model_type` field tells you which of the three concepts it represents.

Top level filters use AND, while individual filters use OR if they accept multiple arguments. That means filters will be resolved like this: `(id IN ids) AND (remote_id IN remote_ids)`

## Query parameters

- `cursor` string — An optional cursor string used for pagination. This can be retrieved from the `next` property of the previous page response.
- `page_size` integer — The number of results to return per page. Maximum is 250.
- `updated_after` string, date-time — Filter the entries based on the modification date in format `YYYY-MM-DDTHH:mm:ss.sssZ`. Returns records where either the record itself **OR** its nested data has been updated since this timestamp, even if the record's own `changed_at` field remains unchanged. If you want to track entry deletion, also set the `include_deleted=true` query parameter, because otherwise, deleted entries will be hidden. For more details, see [Understanding changed_at vs updated_after Behavior](https://docs.kombo.dev/ats/getting-started/fetching-data#understanding-changed_at-vs-updated_after-behavior). For this endpoint, `updated_after` matches when the returned record changed, or when related data changed as described below. | Path | Added/Removed | Linked Record | | --- | --- | --- | | `locations` | ✓ Yes | ✓ Yes | | `legal_entities` | ✓ Yes | ✓ Yes | | `groups` | ✓ Yes | ✓ Yes | | `skills` | ✓ Yes | ✓ Yes | _**Added/Removed**: Whether adding or removing entries from this list triggers an update (n/a for single records). **Linked Record**: Whether changes to the linked record itself trigger an update._
- `include_deleted` 'true' | 'false' — By default, deleted entries are not returned. Use the `include_deleted` query param to include deleted entries too.
- `ignore_unsupported_filters` 'true' | 'false' — When set to `true`, filters targeting fields not supported by this integration will be ignored instead of filtering out all results.
- `ids` string — Filter by a comma-separated list of IDs such as `222k7eCGyUdgt2JWZDNnkDs3,B5DVmypWENfU6eMe6gYDyJG3`.
- `remote_ids` string — Filter by a comma-separated list of remote IDs.
- `model_types` string — Filter by a comma-separated list of `JOB`, `POSITION`, `REQUISITION` Leave this blank to get results matching all values.
- `statuses` string — Filter by a comma-separated list of `OPEN_LIMITED`, `OPEN_UNLIMITED`, `PENDING`, `FROZEN`, `FILLED`, `CLOSED` Leave this blank to get results matching all values.

## Headers

- `X-Integration-Id` string, required

## Response `200`

GET /hris/staffing-entities Positive response

- GetHrisStaffingEntitiesPositiveResponse
  - `status` 'success', required
  - `data` object, required
    - `next` string, nullable, required — Cursor string that can be passed to the `cursor` query parameter to get the next page. If this is `null`, then there are no more pages.
    - `results` object[], required
      - `id` string, required — The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing.
      - `remote_id` string, required — The raw ID of the object in the remote system. We don't recommend using this as a primary key on your side as it might sometimes be compromised of multiple identifiers if a system doesn't provide a clear primary key.
      - `name` string, nullable, required — The name/title of the staffing entity.
      - `model_type` 'JOB' | 'POSITION' | 'REQUISITION', nullable, required — The remote model type of the record. Possible values are "JOB", "POSITION" or "REQUISITION". We recommend that users of our `create employee` endpoint ask the customer whether they want to hire into positions or requisitions.
      - `description` string, nullable, required — A text description of the staffing entity — typically covering responsibilities, requirements, and scope. Commonly referred to as the "job description" in HRIS systems. May contain HTML, depending on the source system.
      - `status` 'OPEN_LIMITED' | 'OPEN_UNLIMITED' | 'PENDING' | 'FROZEN' | 'FILLED' | 'CLOSED', nullable, required — The status of the staffing entity. OPEN_LIMITED: The staffing entity is open and has a limited number of openings. Refer to the `number_of_openings` field to get the number of openings. OPEN_UNLIMITED: The staffing entity is open and has an unlimited number of openings. Some enterprise systems refer to this as "Evergreen". PENDING: The staffing entity is pending approval or is waiting to be published. FROZEN: The staffing entity is frozen (hiring freeze) and does not accept applications/hires. FILLED: The staffing entity is filled (to its maximum capacity) and not available for new hires. CLOSED: The staffing entity is closed and not available for new hires.
      - `employment_types` object[], nullable — The employment types available for/used by the staffing entity. Use the `remote_label` for display in your UI as it is consistent with the language of the remote system. Use the `unified_type` for internal categorization as it is unified across all tools.
        - `remote_label` string, required — The label of the employment type how it appears in the remote system.
        - `unified_type` 'FULL_TIME' | 'PART_TIME' | 'CONTRACT' | 'INTERNSHIP' | 'FREELANCE' | 'WORKING_STUDENT' | 'APPRENTICESHIP' | 'TRAINING', nullable, required — The unified type, how Kombo categorize this label.
      - `number_of_openings` number, double, nullable, required — The number of openings for the staffing entity. Only meaningful for staffing entities with the status "OPEN_LIMITED".
      - `parent_id` string, nullable, required — The Kombo ID of the staffing entity’s parent. Usually it’s the position/job that was used to create the requisition. The ID can be used to retrieve the parent staffing entity from the `get staffing entity` endpoint.
      - `remote_url` string, uri, nullable, required — URL to the staffing entity in the HRIS system. Use this to implement backlinks into the HRIS/Enterprise System.
      - `remote_created_at` string, date-time, nullable, required — The date and time the object was created in the remote system.
      - `remote_updated_at` string, date-time, nullable, required — A timestamp retrieved from the remote system, describing when the resource was last updated.
      - `changed_at` string, date-time, required — The timestamp when this specific record was last modified. This field only updates when properties directly on this record change, NOT when related or nested models change. For filtering that considers nested data changes, use the `updated_after` parameter which will return records when either the record itself OR its related models have been updated.
      - `remote_deleted_at` string, date-time, nullable, required — The date and time the object was deleted in the remote system. Objects are automatically marked as deleted when Kombo can't retrieve them from the remote system anymore. Kombo will also anonymize entries 14 days after they disappear.
      - `custom_fields` object, nullable, required — A key-value store of fields not covered by the schema. [Read more](/custom-fields)
      - `integration_fields` object[], required — An array of selected passthrough integration fields. [Read more](/integration-fields)
        - `id` string, required — The globally unique ID of this object.
        - `key` string, required — The key of the field in the remote system.
        - `type` 'DEFAULT' | 'CUSTOM', required — - `DEFAULT`: static fields in the remote system. - `CUSTOM`: fields that are created/editable by the user.
        - `value` unknown
        - `label` string, nullable, required — The label of the field. (not always available)
      - `remote_data` object, nullable, required — Includes the data fetched from the remote system. Please be aware that including this in you scope config might violate other scopes that are set. Remote data always has the endpoint path that we got the data from as the top level key. For example, it could look like: `{ "/companies": { ... }}` This is not available on all plans. Reach out to Kombo if you need it.
      - `locations` object[], required — The physical work locations associated with this staffing entity. A position or requisition can be linked to one or more offices or sites where the role is to be filled.
        - `id` string, required — The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing.
        - `remote_id` string, nullable, required — The raw ID of the object in the remote system. We don't recommend using this as a primary key on your side as it might sometimes be compromised of multiple identifiers if a system doesn't provide a clear primary key.
        - `name` string, nullable, required — The work location’s name
        - `type` string, nullable, required — The work location’s type. A freeform string.
      - `legal_entities` object[], required — The legal entities (companies or sub-companies) associated with this staffing entity. Indicates which employing entities within the organization the position or requisition belongs to.
        - `id` string, required — The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing.
        - `remote_id` string, nullable, required — The raw ID of the object in the remote system. We don't recommend using this as a primary key on your side as it might sometimes be compromised of multiple identifiers if a system doesn't provide a clear primary key.
        - `name` string, nullable, required — The legal entity’s name.
      - `groups` object[], required — The organizational groups (such as departments, teams, or cost centers) associated with this staffing entity.
        - `id` string, required — The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing.
        - `remote_id` string, required — The raw ID of the object in the remote system. We don't recommend using this as a primary key on your side as it might sometimes be compromised of multiple identifiers if a system doesn't provide a clear primary key.
        - `name` string, nullable, required — The name of the group.
        - `type` 'DEPARTMENT' | 'TEAM' | 'COST_CENTER', nullable, required — Type of the group.
      - `skills` object[], required — The skills expected on this staffing entity (role), with the expected proficiency level per skill.
        - `skill_id` string, required — The Kombo ID of the skill. Can be used to retrieve the skill from the `get skills` endpoint.
        - `skill` object, required — The skill expected for this staffing entity.
          - `id` string, required — The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing.
          - `remote_id` string, required — The raw ID of the object in the remote system. We don't recommend using this as a primary key on your side as it might sometimes be compromised of multiple identifiers if a system doesn't provide a clear primary key.
          - `name` string, nullable, required — The name of the skill, in the default locale of the remote system.
          - `proficiency_scale` union, required — The scale used to rate this skill, useful when writing a rating back. `null` when the skill has no scale.
            - object
              - …
            - object
              - …
        - `expected_proficiency` union — The expected proficiency for this role. `null` when the source system carries no proficiency on the role side.
          - object
            - `type` 'NUMERIC', required
            - `value` number, double, required — The numeric proficiency value on the scale.
          - object
            - `type` 'SINGLE_SELECT', required
            - `selected_option_id` string, required — The Kombo ID of the selected option on the scale (`proficiency_scale.ordered_options[].id`).

## Other responses

- `default` — The standard error response with the error codes for the HRIS use case.

---

[API](https://skmtc.net/kombo/apis/kombo-api.md) · [All operations](https://skmtc.net/kombo/apis/kombo-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kombo/kombo-api/revisions/149bf44faf1a/schema)