Rippling: Retrieve a specific headcount position
Rippling restApi.getHeadcountPositions: arguments, response, policy and SDK examples.
← Rest API operations · Get started
Operation rippling.rest_api.get_headcount_positions
Provider route: GET /headcount-positions/{id}/. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “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 osfrom alter_sdk import Appfrom 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()| 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
Section titled “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
Schemas
Section titled “Schemas”35 more schemas are linked from the tables above, on the schema pages.
Retrieve a report run — response body — meta redacted fields item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Info about the redacted fields. |
name | string | Optional | The name for the redacted field |
reason | string | Optional | The reason for the redaction |
Update a team — response body — parent
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
created_at | string | Required within parent | Record creation date |
id | string | Required within parent | Identifier field |
name | string | Required within parent | The name of the team. |
parent | Model | Optional | Expand Update a team — response body — parent The parent team Expandable field |
parent_id | string | Optional | The parent team |
updated_at | string | Required within parent | Record update date |
Referenced models: Update a team — response body — parent
Retrieve a specific headcount position — response body — actual compensation
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Compensation data synched from worker compensation |
base_pay | object | Optional | Annual base pay for the headcount position |
base_pay.currency_type | string | Optional | The currency type, ex: USD, EUR, etc. |
base_pay.value | JSON | Optional | |
base_pay.value (anyOf 1) | number | Alternative | The decimal amount for the currency. |
base_pay.value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
bonus | object | Optional | Annual bonus for the headcount position |
bonus.currency_type | string | Optional | The currency type, ex: USD, EUR, etc. |
bonus.value | JSON | Optional | |
bonus.value (anyOf 1) | number | Alternative | The decimal amount for the currency. |
bonus.value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
commission | object | Optional | Annual on target commission for the headcount position |
commission.currency_type | string | Optional | The currency type, ex: USD, EUR, etc. |
commission.value | JSON | Optional | |
commission.value (anyOf 1) | number | Alternative | The decimal amount for the currency. |
commission.value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
tax_and_benefits | object | Optional | Annual total taxes and benefits compensation for this headcount position |
tax_and_benefits.currency_type | string | Optional | The currency type, ex: USD, EUR, etc. |
tax_and_benefits.value | JSON | Optional | |
tax_and_benefits.value (anyOf 1) | number | Alternative | The decimal amount for the currency. |
tax_and_benefits.value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
total_cash | object | Optional | Annual total cash compensation for the headcount position |
total_cash.currency_type | string | Optional | The currency type, ex: USD, EUR, etc. |
total_cash.value | JSON | Optional | |
total_cash.value (anyOf 1) | number | Alternative | The decimal amount for the currency. |
total_cash.value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
total_equity | object | Optional | Annual total equity compensation for the headcount position |
total_equity.currency_type | string | Optional | The currency type, ex: USD, EUR, etc. |
total_equity.value | JSON | Optional | |
total_equity.value (anyOf 1) | number | Alternative | The decimal amount for the currency. |
total_equity.value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
Retrieve a specific headcount position — response body — comp band compensation
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Compensation data defined through comp band |
base_pay | object | Optional | Annual base pay for the headcount position |
base_pay.currency_type | string | Optional | The currency type, ex: USD, EUR, etc. |
base_pay.value | JSON | Optional | |
base_pay.value (anyOf 1) | number | Alternative | The decimal amount for the currency. |
base_pay.value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
bonus | object | Optional | Annual bonus for the headcount position |
bonus.currency_type | string | Optional | The currency type, ex: USD, EUR, etc. |
bonus.value | JSON | Optional | |
bonus.value (anyOf 1) | number | Alternative | The decimal amount for the currency. |
bonus.value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
commission | object | Optional | Annual on target commission for the headcount position |
commission.currency_type | string | Optional | The currency type, ex: USD, EUR, etc. |
commission.value | JSON | Optional | |
commission.value (anyOf 1) | number | Alternative | The decimal amount for the currency. |
commission.value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
tax_and_benefits | object | Optional | Annual total taxes and benefits compensation for this headcount position |
tax_and_benefits.currency_type | string | Optional | The currency type, ex: USD, EUR, etc. |
tax_and_benefits.value | JSON | Optional | |
tax_and_benefits.value (anyOf 1) | number | Alternative | The decimal amount for the currency. |
tax_and_benefits.value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
total_cash | object | Optional | Annual total cash compensation for the headcount position |
total_cash.currency_type | string | Optional | The currency type, ex: USD, EUR, etc. |
total_cash.value | JSON | Optional | |
total_cash.value (anyOf 1) | number | Alternative | The decimal amount for the currency. |
total_cash.value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
total_equity | object | Optional | Annual total equity compensation for the headcount position |
total_equity.currency_type | string | Optional | The currency type, ex: USD, EUR, etc. |
total_equity.value | JSON | Optional | |
total_equity.value (anyOf 1) | number | Alternative | The decimal amount for the currency. |
total_equity.value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
Retrieve a specific headcount position — response body — department
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Department the headcount belongs to Expandable field |
created_at | string | Required within parent | Record creation date |
department_hierarchy | array | Optional | List of departments in the department hierarchy. Refer department_hierarchy_ids for department hierarchy order. Expandable field |
department_hierarchy[] | Model | Each item | Expand Update a department — response body — parent |
department_hierarchy_id | array | Optional | The identifier of departments in the department hierarchy ordered from parent department to child department. |
department_hierarchy_id[] | string | Each item | |
id | string | Required within parent | Identifier field |
name | string | Required within parent | The name of the department. |
parent | Model | Optional | Expand Update a department — response body — parent The parent department. Expandable field |
parent_id | string | Optional | The parent department. |
reference_code | string | Optional | Reference code of the department. |
updated_at | string | Required within parent | Record update date |
Referenced models: Update a department — response body — parent
Retrieve a specific headcount position — response body — employment type
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Employment type the headcount is assigned to Expandable field |
amount_worked | string | Optional | The amount worked for the employment type. * `FULL-TIME`: Full-time is at least 30 hours per week. Full-time workers will typically be eligible for benefits. * `PART-TIME`: Part-time is less than 30 hours per week. These workers may be eligible for benefits, depending on company settings and hours worked. * `TEMPORARY`: These workers are hired on a temporary basis. You can specify how each worker with this employment type will be paid individually. Known values: PART-TIME, FULL-TIME, TEMPORARY |
compensation_time_period | string | Optional | The compensation period for the employment type. * `SALARIED`: Employees that are paid a fixed amount per year. * `HOURLY`: Employees that are paid a wage per hour worked. Known values: HOURLY, SALARIED |
created_at | string | Required within parent | Record creation date |
id | string | Required within parent | Identifier field |
label | string | Required within parent | The display label of the employment type. |
name | string | Optional | The name of the employment type for non-custom employment types. |
type | string | Optional | The classification of the worker by the company. * `CONTRACTOR`: Contractors are self-employed workers who provide services on a short-term or per-project basis and are not eligible for tax-withholding or benefits. * `EMPLOYEE`: Employees are hired and managed by an employer, work under the employer's direct supervision and control, and are protected by law for wages and employment rights. Known values: CONTRACTOR, EMPLOYEE |
updated_at | string | Required within parent | Record update date |
Policy, approvals and errors
Section titled “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"}