> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kombo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Staffing entities

> Staffing entities endpoints overview, data structure, model_types, and API usage.

<Warning>
  **Beta Feature:** These endpoints are currently in beta. Please reach out to
  our support team if you need assistance with implementation.
</Warning>

## Overview

The staffing entities endpoint provides a unified way to read hiring structures
from HRIS systems. It normalizes records that are often called **positions**,
**requisitions**, or **jobs** so you can implement one integration flow across
different providers.

This feature is especially useful when your product needs to:

* show available hiring slots for the creation of job requisitions or job postings
* assign newly hired employee to the correct org structure and legal entity
* build approvals or workflows around hiring demand
* distinguish one-off backfills from evergreen hiring

<Note>
  For full request/response details and all supported query parameters, see
  <a href="/hris/v1/get-staffing-entities">GET staffing entities</a>.
</Note>

## Understanding Position vs Requisition vs Job

HRIS systems do not use these terms consistently, but a common pattern is:

* **Position**: structural slot in the organization, often tied to department,
  manager, location, and budget
* **Requisition**: request to fill a role, usually approval-driven and often
  linked to a parent position
* **Job**: generic hiring object in some systems, frequently used for
  lightweight or evergreen hiring flows

In Kombo, each record includes `model_type` with one of:

* `POSITION`
* `REQUISITION`
* `JOB`

If your workflow creates employees, we strongly recommend asking each customer
whether they hire into positions or requisitions first, then filtering data
using `model_types`.

## API Surface

<CardGroup cols={2}>
  <Card title="Get staffing entities" icon="list" href="/hris/v1/get-staffing-entities">
    Retrieve staffing entities and filter by model type or status.
  </Card>

  <Card title="Get employee form" icon="users" href="/hris/v1/get-employees-form">
    Get an adjusted employee creation form after selecting the correct target
    staffing entity.
  </Card>

  <Card title="Create employee with form" icon="user-plus" href="/hris/v1/post-employees-form">
    Create employees with the target staffing entity.
  </Card>

  <Card title="Implementation guide" icon="book-open" href="/hris/implementation-guide/staffing-entities-in-create-employee">
    End-to-end walkthrough: how to use staffing entities when creating
    employees, including the picker flow and form scoping.
  </Card>
</CardGroup>

## Key Properties

### Identity and classification

* `id`: Kombo ID
* `remote_id`: provider ID
* `name`: title/name of the entity
* `model_type`: `JOB`, `POSITION`, or `REQUISITION`
* `parent_id`: parent staffing entity (commonly a requisition -> position link)

### Hiring context

* `status`: one of `OPEN_LIMITED`, `OPEN_UNLIMITED`, `PENDING`, `FROZEN`,
  `FILLED`, `CLOSED`
* `number_of_openings`: number of openings (mainly meaningful for
  `OPEN_LIMITED`)
* `description`: often equivalent to a job description and can include HTML
* `employment_types`: unified + remote labels for contract type classification

### Organizational links

* `locations`: related work locations
* `legal_entities`: related employing entities/sub-companies
* `groups`: related departments/teams/cost centers

### Integration metadata

* `remote_url`: deep link to the record in the source HRIS
* `custom_fields`: normalized custom fields for this model
* `integration_fields`: provider-specific passthrough fields (if enabled)
* `remote_created_at`, `remote_updated_at`, `changed_at`, `remote_deleted_at`
* `remote_data`: raw provider payload (if configured)

## Filtering and Retrieval Patterns

Common query filters include:

* `model_types`: filter to `POSITION`, `REQUISITION`, `JOB`
* `statuses`: filter by lifecycle status
* standard list filters like IDs, pagination, and update windows

Example patterns:

```bash theme={null}
GET /hris/staffing-entities?model_types=POSITION,JOB&statuses=OPEN_LIMITED,OPEN_UNLIMITED
GET /hris/staffing-entities?model_types=REQUISITION&statuses=PENDING,OPEN_LIMITED,OPEN_UNLIMITED
```

## Implementation Tips

1. Pick one primary hiring object per customer (`POSITION` and `JOB`, or `REQUISITION`)
   and persist that choice in your integration settings.
2. Treat `OPEN_UNLIMITED` as evergreen hiring and avoid interpreting
   `number_of_openings` as a hard limit there.
3. Use `parent_id` to build drill-down UIs (for example requisition -> position
   lineage).
4. Use `remote_url` for "Open in HRIS" backlinks in operational workflows.
5. Prefer `remote_label` for UI components and `unified_type` for internal filtering logic when using
   `employment_types`.

<Card title="Using staffing entities when creating employees" icon="user-plus" href="/hris/implementation-guide/staffing-entities-in-create-employee" arrow={true}>
  Full workflow for the hire-into-position flow — from picker UI through form
  scoping to POST submission.
</Card>