Rippling: List headcount positions — response body — results item

API reference · Contract 2026-10-28

SDK schema: List headcount positions — response body — results item

Field	Type	Presence	Description and constraints
$	object	Root
actual_compensation	Model	Optional	Expand Retrieve a specific headcount position — response body — actual compensation
backfill_for	Model	Optional	Expand Retrieve a specific headcount position — response body — backfill for
backfill_for_id	string	Optional	ID of the worker for whom this headcount position was requested as a backfill
comp_band_compensation	Model	Optional	Expand Retrieve a specific headcount position — response body — comp band compensation
created_at	string	Required within parent	Record creation date
current_start_date	string	Optional	Most recent start date estimate or the actual hire date if already filled
department	Model	Optional	Expand Retrieve a specific headcount position — response body — department
department_id	string	Optional	ID for the department the headcount belongs to
employment_type	Model	Optional	Expand Retrieve a specific headcount position — response body — employment type
employment_type_id	string	Optional	ID for the employment type the headcount is assigned to
end_date	string	Optional	Targeted end date for the headcount
headcount_owner	Model	Optional	Expand Retrieve a specific headcount position — response body — headcount owner
headcount_owner_id	string	Optional	ID for the headcount owner
id	string	Required within parent	Identifier field
in_budget	boolean	Optional	Whether the headcount position is in budget
job_function	object	Optional	Job function assigned to this headcount Expandable field
job_function.created_at	string	Required within parent	Record creation date
job_function.id	string	Required within parent	Identifier field
job_function.name	string	Optional	Displayed name of the job function
job_function.updated_at	string	Required within parent	Record update date
job_function_id	string	Optional	ID for the job function the headcount is assigned to
job_requisition	Model	Optional	Expand Retrieve a specific headcount position — response body — job requisition
job_requisition_id	string	Optional	ID for the job requisition the headcount is associated with
level	Model	Optional	Expand Retrieve a specific headcount position — response body — level
level_id	string	Optional	ID for the level the headcount is assigned to
location_factor	Model	Optional	Expand Retrieve a specific headcount position — response body — location factor
location_factor_id	string	Optional	ID for the location factor the headcount is assigned to
notes	string	Optional	Headcount notes
position_id	string	Optional	Position name for the headcount, for ex PID100037
position_sub_type	string	Optional	More granular classification of headcount position type. `NEW` New headcount created, typically paired with the OPEN_HEADCOUNT type. `BACKFILL` Replacement headcount for someone who left the company. `FORECASTED_ATTRITION` Headcount that does not count toward the budget, also known as provisional position in the application, `HIRING_STAGE` Person is going through the hiring process, paired with the FUTURE_START type. `OFFER_STAGE` Offer has been extended to a candidate, awaiting their decision. Paired with the FUTURE_START type. `OFFER_ACCEPTED` Candidate has accepted the offer but has not yet started. Paired with the FUTURE_START type. `PLAN_CHANGE` Headcount status changed due to business decision. Paired with CLOSED type. `TERMINATED` Role was filled, but the employee was separated from the company. Paired with CLOSED type. `TRANSFERRED` Employee moved internally to another role. Paired with CLOSED type. Known values: NEW, BACKFILL, FORECASTED_ATTRITION, HIRING_STAGE, OFFER_STAGE, OFFER_ACCEPTED, PLAN_CHANGE, TERMINATED, TRANSFERRED
position_type	string	Optional	Type of headcount position. `OPEN_HEADCOUNT` A headcount position that’s not yet filled. `FUTURE_START` Headcount where a candidate is going through the hiring process, or an offer has been accepted, but the person has not yet started. `ACTIVE` Headcount where a candidate has been hired and started. `CLOSED` Headcount that’s no longer available to fill. Known values: OPEN_HEADCOUNT, FUTURE_START, ACTIVE, CLOSED
priority	object	Optional	Priority assigned to this headcount Expandable field
priority.created_at	string	Required within parent	Record creation date
priority.id	string	Required within parent	Identifier field
priority.name	string	Optional	Display name of the headcount priority
priority.updated_at	string	Required within parent	Record update date
priority_id	string	Optional	ID for the headcount priority
recruiter	Model	Optional	Expand Retrieve a specific headcount position — response body — recruiter
recruiter_id	string	Optional	ID for the recruiter working on filling the position
target_start_date	string	Optional	The estimated start date when the position was first created
teams	array	Optional	Teams the headcount belongs to Expandable field
teams[]	Model	Each item	Expand Update a team — response body — parent
teams_id	array	Optional	IDs for the teams the headcount belongs to
teams_id[]	string	Each item
title	string	Optional	Job title for the position. For a vacant headcount position, this can be defined on creation. Once the position is occupied, it’s synched from the associated worker’s job title.
updated_at	string	Required within parent	Record update date
work_location	Model	Optional	Expand Retrieve a specific headcount position — response body — work location
work_location_id	string	Optional	ID for the work location the headcount is assigned to
worker	Model	Optional	Expand Retrieve a specific headcount position — response body — worker
worker_id	string	Optional	ID for the worker hired into the headcount

Referenced models: Update a team — response body — parent, Retrieve a specific headcount position — response body — actual compensation, Retrieve a specific headcount position — response body — backfill for, Retrieve a specific headcount position — response body — comp band compensation, Retrieve a specific headcount position — response body — department, Retrieve a specific headcount position — response body — employment type, Retrieve a specific headcount position — response body — headcount owner, Retrieve a specific headcount position — response body — job requisition, Retrieve a specific headcount position — response body — level, Retrieve a specific headcount position — response body — location factor, Retrieve a specific headcount position — response body — recruiter, Retrieve a specific headcount position — response body — work location, Retrieve a specific headcount position — response body — worker