Create Employee Form with Staffing Entities

​

Overview

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 and POST /hris/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.

​

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.

​

End-to-end flow

​

Phase 1 — Linking a staffing entity to a requisition

1

Check if the integration supports staffing entities

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 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.

2

Fetch available staffing entities

Use GET /hris/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:

Example: open positions/jobs/requisitions only

GET /hris/staffing-entities?statuses=OPEN_LIMITED,OPEN_UNLIMITED

Example: requisitions only

GET /hris/staffing-entities?model_types=REQUISITION

Example: open requisitions only

GET /hris/staffing-entities?model_types=REQUISITION&statuses=OPEN_LIMITED,OPEN_UNLIMITED

3

Render the picker inside your requisition editor

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.

4

Prefill requisition fields from the selected entity (recommended)

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.

5

Persist `staffing_entity_id` on the requisition

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

GET /hris/employees/form?staffing_entity_id=26vafvWSRmbhNcxJYqjCzuJg

{
  "staffing_entity_id": "26vafvWSRmbhNcxJYqjCzuJg",
  "properties": {
    "firstName": "Jane",
    "lastName": "Doe",
    "startDate": "2025-02-01",
    "workLocation": {
      "site": "remote:office_berlin"
    }
  }
}

​

How the form changes with a staffing entity

• 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.

​

Preselect fields with only one option

• 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.

​

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