Rippling: Retrieve a specific headcount position

← rest_api operations · Get started · OpenAPI downloads

Contract 2026-10-28 · Operation rippling.rest_api.get_headcount_positions

Provider route: GET /headcount-positions/{id}/. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/rippling with npm, or alter-sdk-rippling with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { RipplingIntegration } from "@alter-ai/rippling";

async function execute(input: Parameters<RipplingIntegration["restApi"]["getHeadcountPositions"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new RipplingIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.restApi.getHeadcountPositions(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_rippling import RipplingIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = RipplingIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.rest_api.get_headcount_positions(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.id	string	Required within parent	Format: id
query	object	Optional	Additional keys: not allowed
query.expand	string	Optional

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	object	Root
__meta	object	Optional
__meta.redacted_fields	array	Optional
__meta.redacted_fields[]	Model	Each item	Expand Retrieve a report run — response body — meta redacted fields item
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: Retrieve a report run — response body — meta redacted fields item, 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

Policy, approvals and errors

SDK function policy ID: rippling.rest_api.get_headcount_positions. Catalog operation: get-headcount-positions. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Required provider scopes: ["headcount-positions.read"]

Provider entitlements: ["API_Tier_1"]

Pinned headers: {"Rippling-Api-Version": "2024-08-01"}

Official provider source