Rippling: Create hire
Rippling restApi.createHires: arguments, response, policy and SDK examples.
← Rest API operations · Get started
Operation rippling.rest_api.create_hires
Provider route: POST /hires/. 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"]["createHires"]>[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.createHires(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.create_hires(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
headers | object | Required within parent | Additional keys: not allowed |
headers.Idempotency-Key | string | Required within parent | |
body | Model | Required within parent | Expand Create hire — request body — body |
Referenced models: Create hire — request body — body
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 |
|---|---|---|---|
$ | JSON | Root | |
$ (anyOf 1) | Model | Alternative | Expand Create hire — response body — results |
$ (anyOf 2) | Model | Alternative | Expand Create hire — response body — results |
Referenced models: Create hire — response body — results
Schemas
Section titled “Schemas”15 more schemas are linked from the tables above, on the schema pages.
Create hire — response body — results
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
results | array | Required within parent | One result per request hire, in request order. HTTP 200 means the envelope was accepted; each item's status is the outcome. |
results[] | Model | Each item | Expand Create hire — response body — results results item |
Referenced models: Create hire — response body — results results item
Create hire — request body — body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
hires | array | Required within parent | One to five hire submissions. Results are returned in the same order. |
hires[] | Model | Each item | Expand Create hire — request body — body hires item |
Referenced models: Create hire — request body — body hires item
Create hire — response body — results results item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
client_request_id | string | Optional | Echo of the caller-supplied item id. |
errors | array | Optional | Structured item errors using the same public field paths as GET /hire-requirements/. |
errors[] | Model | Each item | Expand Create hire — response body — results results item errors item |
existing_role_id | string | Optional | Matching existing role id for duplicate or rehire conflicts. |
id | string | Optional | Rippling hire role id when a role exists. |
missing_required_fields | array | Optional | Public field paths still required before review. |
missing_required_fields[] | string | Each item | |
next_actions | array | Optional | Actions for duplicate, rehire, or Auto-Hire failures and blockers. |
next_actions[] | Model | Each item | Expand Create hire — response body — results results item next actions item |
pending_fields | array | Optional | Accepted public field paths not yet active because progression is blocked. |
pending_fields[] | string | Each item | |
status | string | Required within parent | ready_for_review, auto_hire_processing, incomplete, or failed. auto_hire_processing includes hires awaiting approval or asynchronous completion. |
Referenced models: Create hire — response body — results results item errors item, Create hire — response body — results results item next actions item
Create hire — response body — results results item errors item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
code | string | Required within parent | Machine-readable error code. |
field | string | Optional | Public field path when the error is field-scoped. |
message | string | Required within parent | Human-readable error message. |
Create hire — response body — results results item next actions item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
code | string | Required within parent | Machine-readable next action. Supported values: - `continue_existing_hire`: Continue the matching in-progress hire. - `provide_rehire_choice`: Choose how to rehire the matching former worker. When Auto-Hire is enabled and blocked or fails to start: - `assign_device_in_rippling`: Assign a device in Rippling. - `provide_document_values`: Complete missing document details. - `review_devices_in_rippling`: Review devices in Rippling. - `review_documents_in_rippling`: Review documents in Rippling. - `review_work_email_in_rippling`: Review work email in Rippling. - `review_work_pattern_in_rippling`: Review the work pattern in Rippling. - `review_retirement_in_rippling`: Review retirement enrollment in Rippling. - `configure_offer_notification`: Configure the offer notification. - `provide_missing_hire_input`: Complete missing hire details. - `review_hire_in_rippling`: Review the hire in Rippling. - `resolve_hire_issue_in_rippling`: Resolve the hire issue in Rippling. |
target_id | string | Optional | Role id the caller should continue, when applicable. |
Create hire — request body — body hires item custom fields item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
field_id | string | Required within parent | Identifier of a company-configured custom field collected during hiring. Use a field configured for the hiring company. |
value | object | Required within parent | Value for the selected custom field. Its JSON type and allowed options depend on that field's configuration in Rippling. |
Create hire — request body — body hires item compensation base pay amount
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Gross base-pay rate for one base_pay_period, before bonuses, commission, equity, or allowances. Provide currency_type as a three-letter ISO 4217 code and value as a nonnegative decimal amount. Use zero when the hire has no base pay, including supported zero-pay contractor arrangements. |
currency_type | string | Optional | The currency type, ex: USD, EUR, etc. |
value | number | Optional | The decimal amount for the currency. |
Create hire — request body — body hires item employment collective bargaining
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Collective-bargaining coverage and the applicable agreement identifiers. Additional keys: not allowed |
agreement_code | string | Optional | Official country-specific identifier of the applicable collective bargaining agreement. This is an external statutory code, not a Rippling resource ID; GET /hire-requirements/ describes its source and format for the selected country. |
agreement_name | string | Optional | Name of the employer's applicable collective labor or bargaining agreement. Provide it only when a named agreement applies; other union activity does not require a name. Use an allowed value from GET /hire-requirements/. |
area | string | Optional | Geographic or industry area governed by the agreement. |
coverage | string | Optional | Whether a collective bargaining agreement covers the worker. One of: COVERED, NOT_COVERED |
group | string | Optional | Worker group or category within the applicable agreement. |
has_union_activity | boolean | Optional | Whether the employer has a collective labor agreement, collective bargaining agreement, or other union activity in place. This is an employer-level fact and is distinct from whether an agreement covers this worker. |
Create hire — request body — body hires item compensation commission
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Variable sales compensation expected when the person meets target. on_target_amount is required; provide payment_frequency where required by GET /hire-requirements/. Starting with API version 2025-08-01, this field does not apply to contractor hires and is reported in ignored_fields. Additional keys: not allowed |
on_target_amount | object | Required within parent | Expected total commission for a full year when the person meets target, using currency_type as a three-letter ISO 4217 code and value as the decimal amount. |
on_target_amount.currency_type | string | Optional | The currency type, ex: USD, EUR, etc. |
on_target_amount.value | number | Optional | The decimal amount for the currency. |
payment_frequency | string | Optional | How often commission is paid: MONTH, QUARTER, or YEAR. Required when indicated by GET /hire-requirements/ for the selected country and hire type. One of: MONTH, QUARTER, YEAR |
Create hire — request body — body hires item employment contract
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Employment term: ongoing with no predetermined end or fixed for a defined term. Additional keys: not allowed |
duration | object | Optional | Exact fixed-term length. Use only with type FIXED; omit for INDEFINITE. Additional keys: not allowed |
duration.unit | string | Required within parent | Duration unit: DAYS, WEEKS, MONTHS, or YEARS. One of: DAYS, WEEKS, MONTHS, YEARS |
duration.value | integer | Required within parent | Positive number of duration units. |
minimum_guaranteed_duration | object | Optional | Minimum contract length guaranteed to the worker, distinct from the exact total duration. Additional keys: not allowed |
minimum_guaranteed_duration.unit | string | Required within parent | Duration unit: DAYS, WEEKS, MONTHS, or YEARS. One of: DAYS, WEEKS, MONTHS, YEARS |
minimum_guaranteed_duration.value | integer | Required within parent | Positive number of duration units. |
mission | Model | Optional | Expand Create hire — request body — body hires item employment contract mission |
type | string | Required within parent | Whether employment is ongoing or fixed-term. Use INDEFINITE when there is no predetermined end and FIXED when the employment is limited to a defined term. One of: FIXED, INDEFINITE |
Referenced models: Create hire — request body — body hires item employment contract mission
Create hire — request body — body hires item employment notice
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Notice-period arrangement for ending employment: standard or a custom period. Additional keys: not allowed |
quantity | integer | Optional | Number of notice-period units. Required for CUSTOM_NOTICE; omit for STANDARD_NOTICE. |
type | string | Required within parent | Notice-period arrangement for ending employment. STANDARD_NOTICE applies the standard period; CUSTOM_NOTICE supplies a specific period. One of: STANDARD_NOTICE, CUSTOM_NOTICE |
unit | string | Optional | Unit for the custom notice period: DAYS, WEEKS, MONTHS, or YEARS. Required for CUSTOM_NOTICE; omit for STANDARD_NOTICE. One of: DAYS, WEEKS, MONTHS, YEARS |
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: rippling.rest_api.create_hires. Catalog operation: create-hires. 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: ["hires.read-write"]
Provider entitlements: ["Hires_API"]
Pinned headers: {"Rippling-Api-Version": "2024-08-01"}
Source limitations: ["upstream_hire_fields_required_only_for_review"]