> ## 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.
# Create Employee Form with Staffing Entities
> Get a scoped create employee form by implementing and using our **Staffing Entities** model.
## Overview
[Staffing entities](/hris/features/staffing-entities) represent the hiring
structures (positions, requisitions, jobs) inside an HRIS. Many enterprise HRIS
systems (e.g., Workday, UKG Pro, SAP SuccessFactors) require new employees to
be hired **into** one of these entities rather than created as standalone
records.
As an ATS provider, you integrate staffing entities in **two phases**:
1. **Requisition / job posting setup.** When your user creates or edits a
requisition (or job posting — whatever your ATS calls its hiring object),
you let them pick a single staffing entity from the connected HRIS and
store its `staffing_entity_id` on the requisition. Optionally, you prefill
base requisition fields (title, department, location, employment type, ...)
from the selected entity.
2. **Hire.** When an application tied to that requisition reaches the hire
stage, you pass the stored `staffing_entity_id` to
[`GET`](/hris/v1/get-employees-form) and
[`POST /hris/employees/form`](/hris/v1/post-employees-form). Kombo uses it
to both narrow the form (dropdowns are pre-filtered to values linked to the
entity) and to tell the HRIS which position or requisition the new hire
fills.
The staffing entities endpoint is currently in **beta**. Reach out to support
if you'd like it enabled for your instance.
## Why this matters for your customers
* **Correct placement** — The new employee lands in the HRIS position the
customer's HR team has already approved, with the correct reporting line,
cost center, and budget attached.
* **Requisition-driven hiring** — Each ATS requisition is tied back to an
approved HRIS position or requisition for headcount tracking and downstream
approval flows.
* **Prefilled requisition data** — Picking a staffing entity while creating a
requisition lets you prefill title, department, location, legal entity, and
employment type, keeping ATS data consistent with the HRIS.
* **Fewer user errors** — The employee form's dropdown options are automatically
filtered to the values linked to the staffing entity. Users only see values
that make sense for the position/job/requisition.
* **Unlocks enterprise customers** — Enterprise HRIS suites like Workday and UKG
Pro won't accept a bare employee; they need a target position/job/requisition,
making the form bigger and more complex.
Using staffing entities allows you to prefill up to 40% of the creation form,
significantly improving your customer experience and satisfaction.
A quick way to check whether an integration exposes staffing entities (and
which model type) is to visit the connector's page and look under **Supported
Features & Coverage**. For example:
* [UKG Pro HRIS](/hris/connectors/ukgpro)
* [Workday HRIS](/hris/connectors/workday)
## End-to-end flow
### Phase 1 — Linking a staffing entity to a requisition
Not every HRIS connector exposes staffing entities. Before exposing the
staffing entity picker in your requisition / job posting UI, probe
`GET /hris/staffing-entities` for the target integration.
If you believe the target integration should support the staffing entity model,
reach out to us via your dedicated support channel to request the coverage.
Also make sure the **HRIS Staffing Entities** [scope](/hris/features/scopes)
is enabled for the integration — the data must be in Kombo's database for the
endpoint to return results.
If the integration does **not** support staffing entities or returns no
results, hide the picker in your requisition editor and call the form
endpoints **without** `staffing_entity_id` at hire time, just as described
in the base [create employee guide](/hris/implementation-guide/create-employee).
Use [`GET /hris/staffing-entities`](/hris/v1/get-staffing-entities) to pull
the positions, jobs, or requisitions the customer can hire into. Allow your
customer to filter down to what they actually care about:
```bash Example: open positions/jobs/requisitions only theme={null}
GET /hris/staffing-entities?statuses=OPEN_LIMITED,OPEN_UNLIMITED
```
```bash Example: requisitions only theme={null}
GET /hris/staffing-entities?model_types=REQUISITION
```
```bash Example: open requisitions only theme={null}
GET /hris/staffing-entities?model_types=REQUISITION&statuses=OPEN_LIMITED,OPEN_UNLIMITED
```
Expose the staffing entity picker **inside the requisition / job posting
creation and edit flow**, not at hire time. A single staffing entity
should be linked to each requisition.
A good picker shows:
* `name` - main identifier
* `model_type` — useful as a badge if the customer mixes positions/jobs/requisitions
* `status` + `number_of_openings` — so the user knows how many slots are
left
* The first `location` and `legal_entity` so they can clearly attribute the
position inside their organization.
* `remote_url` — use it to link to the HRIS for a quick verification step
Avoid:
* `remote_id` - Often a technical and lengthy UUID. This is usually not the
requisition ID displayed by most ATS modules and therefore could lead to confusion.
* `description` - The description property often includes fully rendered HTML
with a lengthy job description, making it unsuitable for display as part of a
single-select picker.
* `groups` - Staffing entities are often part of multiple groups, making it hard
to render this in a meaningful manner.
* `remote_created_at` and `remote_updated_at` - Those internal timestamps are
usually not displayed anywhere in the HRIS UI, making them unsuitable for
identifying the record.
When the user picks a staffing entity, prefill your own requisition fields
from the entity so the ATS record mirrors the HRIS source of truth:
* `name` → requisition title
* `description` → requisition description
* `employment_types` → requisition contract type
* `locations` → requisition work location
* `legal_entities` → employing entity
* `groups` → department / team / cost center
Users can still override any field after prefill. This both saves typing
and reduces drift between what the requisition says in the ATS and what
the HRIS will ultimately accept at hire time.
Store the Kombo `id` of the chosen staffing entity on your own requisition
/ job posting record. You will reuse this exact id later, at hire time,
for every applicant that reaches the hire stage for this requisition.
Ideally, you link exactly **one** staffing entity per requisition/job posting.
If you want to allow your customer to link multiple staffing entities to a
single requisition in your system, you need a small staffing entity
selector when hiring employees.
### Phase 2 — Using the linked staffing entity at hire time
When an application tied to the requisition reaches the hire stage, pass
the `staffing_entity_id` you stored on the requisition to the
[`GET /hris/employees/form`](/hris/v1/get-employees-form) endpoint:
```bash theme={null}
GET /hris/employees/form?staffing_entity_id=26vafvWSRmbhNcxJYqjCzuJg
```
The response is the **same schema shape** as a normal `GET
/hris/employees/form` call, but with many reference fields
already pre-filtered.
When posting back, include the same `staffing_entity_id` alongside your
collected `properties`:
```json Example request theme={null}
{
"staffing_entity_id": "26vafvWSRmbhNcxJYqjCzuJg",
"properties": {
"firstName": "Jane",
"lastName": "Doe",
"startDate": "2025-02-01",
"workLocation": {
"site": "remote:office_berlin"
}
}
}
```
Kombo uses this to both **validate** the submitted values against the
narrowed form and to **tell the downstream HRIS** which position or
requisition this new hire fills.
Use the **same** `staffing_entity_id` for the `GET` form call and the
`POST` submission. Mixing them (or omitting it on one side) can lead to
validation errors because the form the user filled in may contain
scoped options that no longer exist in the POST-side validation.
The response follows the standard
[create employee response](/hris/implementation-guide/create-employee)
contract — `id`/`remote_id` on immediate creation, or a `prehire.remote_id`
when the HRIS uses a multi-step onboarding flow.
Nothing changes here because the staffing entity was used during creation,
not returned in the response.
## How the form changes with a staffing entity
Passing `staffing_entity_id` does **not** change the overall field types or
the way you render the form — you still get the same schema shape as a
regular `GET /hris/employees/form` call. What the staffing entity does is
let Kombo tailor the form to the selected position or requisition:
* **Some select fields come back with fewer options.** Dropdowns for things
like legal entity, location, or department may be limited to the values
actually linked to the staffing entity, instead of the full org.
* **Some fields may be hidden entirely.** If a property doesn't apply to the
selected staffing entity (e.g., a salary field on a non-salaried
position), Kombo may omit it from the form so users never see it.
* **Some fields may appear that weren't there before.** Certain HRIS systems
expose extra properties that only make sense in the context of a specific
position or requisition — these only show up when a `staffing_entity_id`
is passed.
The exact behavior depends on the HRIS and on how the customer has modeled
their staffing entities. Treat the form returned with `staffing_entity_id`
as the source of truth and render whatever comes back.
### Preselect fields with only one option
A common side effect of scoping the form is that select fields can end up
with **exactly one** valid option — for example, a position tied to a
single legal entity produces a `legal_entity_id` field with just one entry.
When this happens, we recommend **preselecting the value and keeping the
field visible** in your UI. Users should still see what's about to be
submitted — they just don't have another option to pick from:
* **Required fields** — render the field with the single option preselected
and disabled. The user sees the value that will be submitted but can't
change or clear it.
* **Optional fields** — render the field with the single option preselected
but allow the user to unselect it if they don't want to submit a value.
Either way, the value the user sees on screen is exactly what gets sent in
the `POST` payload, which keeps the flow transparent and avoids surprises
downstream in the HRIS.
## Recommendations
* **Automatically persist or allow your customer to save the filter configuration**
used to select the staffing entity in the create/edit view of your requisition/job posting.
* **Put the picker in the requisition editor, not the hire flow.** Selecting
a staffing entity is a setup-time decision tied to the requisition, not a
per-hire decision.
* **Prefill requisition fields** (title, description, employment type,
location, legal entity, groups) from the chosen staffing entity.
* **Store `staffing_entity_id` on the requisition** and reuse the exact same
value on both `GET` and `POST /hris/employees/form` at hire time.
* **Apply default filters.** `statuses=OPEN_LIMITED,OPEN_UNLIMITED` plus
`model_types=REQUISITION` or `model_types=POSITION,JOB` is almost always what
your customers want.
* **Hide the picker on HRISes that don't expose staffing entities** rather
than showing an empty list.
* **Surface `remote_url`.** Your users often want to confirm the position in the
HRIS before committing to link it — a one-click deep link builds trust.
## Related reading
What staffing entities are, model types, and data structure.
Base implementation guide for the dynamic employee form.
API reference for fetching positions, requisitions, and jobs.
API reference for submitting the form.