Skip to content

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.

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 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.create_hires(arguments)
result = await call.wait()
return result.body_json()
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
headersobjectRequired within parentAdditional keys: not allowed
headers.Idempotency-KeystringRequired within parent
bodyModelRequired within parentExpand Create hire — request body — body

Referenced models: Create hire — request body — body

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

FieldTypePresenceDescription and constraints
$JSONRoot
$ (anyOf 1)ModelAlternativeExpand Create hire — response body — results
$ (anyOf 2)ModelAlternativeExpand Create hire — response body — results

Referenced models: Create hire — response body — results

15 more schemas are linked from the tables above, on the schema pages.

Create hire — response body — results
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
resultsarrayRequired within parentOne result per request hire, in request order. HTTP 200 means the envelope was accepted; each item's status is the outcome.
results[]ModelEach itemExpand Create hire — response body — results results item

Referenced models: Create hire — response body — results results item

Create hire — request body — body
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
hiresarrayRequired within parentOne to five hire submissions. Results are returned in the same order.
hires[]ModelEach itemExpand Create hire — request body — body hires item

Referenced models: Create hire — request body — body hires item

Create hire — response body — results results item
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
client_request_idstringOptionalEcho of the caller-supplied item id.
errorsarrayOptionalStructured item errors using the same public field paths as GET /hire-requirements/.
errors[]ModelEach itemExpand Create hire — response body — results results item errors item
existing_role_idstringOptionalMatching existing role id for duplicate or rehire conflicts.
idstringOptionalRippling hire role id when a role exists.
missing_required_fieldsarrayOptionalPublic field paths still required before review.
missing_required_fields[]stringEach item
next_actionsarrayOptionalActions for duplicate, rehire, or Auto-Hire failures and blockers.
next_actions[]ModelEach itemExpand Create hire — response body — results results item next actions item
pending_fieldsarrayOptionalAccepted public field paths not yet active because progression is blocked.
pending_fields[]stringEach item
statusstringRequired within parentready_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
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
codestringRequired within parentMachine-readable error code.
fieldstringOptionalPublic field path when the error is field-scoped.
messagestringRequired within parentHuman-readable error message.
Create hire — response body — results results item next actions item
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
codestringRequired within parentMachine-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_idstringOptionalRole id the caller should continue, when applicable.
Create hire — request body — body hires item custom fields item
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
field_idstringRequired within parentIdentifier of a company-configured custom field collected during hiring. Use a field configured for the hiring company.
valueobjectRequired within parentValue 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
FieldTypePresenceDescription and constraints
$objectRootGross 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_typestringOptionalThe currency type, ex: USD, EUR, etc.
valuenumberOptionalThe decimal amount for the currency.
Create hire — request body — body hires item employment collective bargaining
FieldTypePresenceDescription and constraints
$objectRootCollective-bargaining coverage and the applicable agreement identifiers.
Additional keys: not allowed
agreement_codestringOptionalOfficial 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_namestringOptionalName 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/.
areastringOptionalGeographic or industry area governed by the agreement.
coveragestringOptionalWhether a collective bargaining agreement covers the worker.
One of: COVERED, NOT_COVERED
groupstringOptionalWorker group or category within the applicable agreement.
has_union_activitybooleanOptionalWhether 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
FieldTypePresenceDescription and constraints
$objectRootVariable 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_amountobjectRequired within parentExpected 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_typestringOptionalThe currency type, ex: USD, EUR, etc.
on_target_amount.valuenumberOptionalThe decimal amount for the currency.
payment_frequencystringOptionalHow 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
FieldTypePresenceDescription and constraints
$objectRootEmployment term: ongoing with no predetermined end or fixed for a defined term.
Additional keys: not allowed
durationobjectOptionalExact fixed-term length. Use only with type FIXED; omit for INDEFINITE.
Additional keys: not allowed
duration.unitstringRequired within parentDuration unit: DAYS, WEEKS, MONTHS, or YEARS.
One of: DAYS, WEEKS, MONTHS, YEARS
duration.valueintegerRequired within parentPositive number of duration units.
minimum_guaranteed_durationobjectOptionalMinimum contract length guaranteed to the worker, distinct from the exact total duration.
Additional keys: not allowed
minimum_guaranteed_duration.unitstringRequired within parentDuration unit: DAYS, WEEKS, MONTHS, or YEARS.
One of: DAYS, WEEKS, MONTHS, YEARS
minimum_guaranteed_duration.valueintegerRequired within parentPositive number of duration units.
missionModelOptionalExpand Create hire — request body — body hires item employment contract mission
typestringRequired within parentWhether 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
FieldTypePresenceDescription and constraints
$objectRootNotice-period arrangement for ending employment: standard or a custom period.
Additional keys: not allowed
quantityintegerOptionalNumber of notice-period units. Required for CUSTOM_NOTICE; omit for STANDARD_NOTICE.
typestringRequired within parentNotice-period arrangement for ending employment. STANDARD_NOTICE applies the standard period; CUSTOM_NOTICE supplies a specific period.
One of: STANDARD_NOTICE, CUSTOM_NOTICE
unitstringOptionalUnit for the custom notice period: DAYS, WEEKS, MONTHS, or YEARS. Required for CUSTOM_NOTICE; omit for STANDARD_NOTICE.
One of: DAYS, WEEKS, MONTHS, YEARS

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"]

Official provider source

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.