Rippling: Create bulk draft hire
Rippling restApi.createDraftHires: arguments, response, policy and SDK examples.
← Rest API operations · Get started
Operation rippling.rest_api.create_draft_hires
Provider route: POST /draft-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"]["createDraftHires"]>[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.createDraftHires(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_draft_hires(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
body | Model | Optional | Expand Create bulk draft hire — request body — body |
Referenced models: Create bulk draft 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 |
|---|---|---|---|
$ | object | Root | Response model for bulk draft hire creation. |
invalid_items | array | Optional | List of invalid draft hire requests Default: [] |
invalid_items[] | Model | Each item | Expand Create bulk draft hire — response body — invalid items item |
successful_results | array | Optional | Detailed results for each draft hire item |
successful_results[] | Model | Each item | Expand Create bulk draft hire — response body — invalid items item |
Referenced models: Create bulk draft hire — response body — invalid items item
Schemas
Section titled “Schemas”5 more schemas are linked from the tables above, on the schema pages.
Create bulk draft hire — response body — invalid items item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Result for an individual draft hire creation. |
draft_hire_role_id | string | Optional | Generated draft hire ID if successful |
errors | array | Optional | List of validation errors if any |
errors[] | string | Each item | |
message | string | Optional | Success or error message |
status | string | Required within parent | Status of the creation (success, error, warning) |
Create bulk draft hire — request body — body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
draft_hires | array | Required within parent | List of draft hires |
draft_hires[] | Model | Each item | Expand Create bulk draft hire — request body — body draft hires item |
Referenced models: Create bulk draft hire — request body — body draft hires item
Create bulk draft hire — request body — body draft hires item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A draft hire represents a candidate who has been offered a position but hasn't started yet. This class provides Platform API access to draft hire data stored as RoleWithCompany instances in a candidate state, allowing external systems to create and manage draft hires. |
custom_fields | array | Optional | Custom fields for the draft hire |
custom_fields[] | Model | Each item | Expand Create bulk draft hire — request body — body draft hires item custom fields item |
documents | array | Optional | Documents to attach to this draft hire |
documents[] | Model | Each item | Expand Create a new employee document — response body — items item documents item |
employment_info | object | Required within parent | Employment information for the draft hire position |
employment_info.contract_end_date | string | Optional | Contract end date |
employment_info.currency | string | Optional | Currency |
employment_info.department_id | string | Optional | Department ID |
employment_info.duties | string | Optional | Duties |
employment_info.eeoc_job_classification | string | Optional | EEOC job classification (e.g., EXECUTIVE, MID_LEVEL, PROFESSIONALS, TECHNICIANS, SALES_WORKERS, SUPPORT_WORKERS, CRAFT_WORKERS, OPERATIVES, HELPERS, SERVICE_WORKERS) |
employment_info.employment_type_id | string | Required within parent | Employment type ID |
employment_info.equity_num_shares | integer | Optional | Equity number of shares |
employment_info.equity_value | number | Optional | Equity value |
employment_info.equity_vesting_schedule | Model | Optional | Expand Create bulk draft hire — request body — body draft hires item employment info equity vesting schedule |
employment_info.job_family_id | string | Optional | Job family ID |
employment_info.job_title | string | Optional | Job title |
employment_info.legal_entity_id | string | Optional | Legal entity ID |
employment_info.level_id | string | Optional | Level ID |
employment_info.manager_id | string | Optional | Manager ID |
employment_info.offer_expiration_date | string | Optional | Offer expiration date |
employment_info.on_target_commission | number | Optional | On target commission |
employment_info.overtime_exemption | string | Optional | Overtime exemption One of: exempt, non-exempt |
employment_info.probation_end_date | string | Optional | Probation end date |
employment_info.relocation_reimbursement | number | Optional | Relocation reimbursement |
employment_info.salary_per_unit | number | Optional | Salary per unit |
employment_info.salary_unit | string | Optional | Salary unit |
employment_info.signing_bonus | number | Optional | Signing bonus |
employment_info.start_date | string | Optional | Start date |
employment_info.target_annual_bonus | number | Optional | Target annual bonus |
employment_info.target_annual_bonus_percent | number | Optional | Target annual bonus as a percentage |
employment_info.teams_ids | array | Optional | Teams IDs |
employment_info.teams_ids[] | string | Each item | |
employment_info.title | string | Required within parent | Title |
employment_info.weekly_hours | number | Optional | Weekly hours |
employment_info.work_email | string | Optional | Work email |
headcount_info | object | Optional | Headcount planning info for hiring into a position. If provided, the draft hire will be linked to the specified open headcount allocation. Requires headcount planning to be enabled for the company. |
headcount_info.position_id | string | Required within parent | The Position ID (PID) of the headcount allocation to fill (e.g., PID100615) |
personal_info | object | Required within parent | Personal information for the draft hire candidate |
personal_info.citizenship | string | Optional | Citizenship of the candidate |
personal_info.date_of_birth | string | Optional | Date of birth |
personal_info.emergency_contact_name | string | Optional | Emergency contact name |
personal_info.emergency_contact_phone | Model | Optional | Expand Create bulk draft hire — request body — body draft hires item personal info emergency contact phone |
personal_info.ethnicity | string | Optional | Ethnicity of the candidate |
personal_info.gender | string | Optional | Gender of the candidate |
personal_info.home_address | Model | Optional | Expand Create bulk draft hire — request body — body draft hires item personal info home address |
personal_info.invite_email | string | Required within parent | Invite email of the candidate |
personal_info.locale | Model | Optional | Expand Create bulk draft hire — request body — body draft hires item personal info locale |
personal_info.name | Model | Required within parent | Expand Create bulk draft hire — request body — body draft hires item personal info name |
personal_info.personal_phone | Model | Optional | Expand Create bulk draft hire — request body — body draft hires item personal info personal phone |
personal_info.race | string | Optional | Race of the candidate |
personal_info.ssn | string | Optional | Social security number of the candidate |
work_location_info | object | Required within parent | Work location information |
work_location_info.country_code | string | Optional | Country code of the work location |
work_location_info.is_remote | boolean | Optional | Whether the work location is remote |
work_location_info.location_id | string | Optional | Work location ID |
work_location_info.state_code | string | Optional | State code of the work location |
Referenced models: Create a new employee document — response body — items item documents item, Create bulk draft hire — request body — body draft hires item personal info home address, Create bulk draft hire — request body — body draft hires item custom fields item, Create bulk draft hire — request body — body draft hires item employment info equity vesting schedule, Create bulk draft hire — request body — body draft hires item personal info locale, Create bulk draft hire — request body — body draft hires item personal info name, Create bulk draft hire — request body — body draft hires item personal info personal phone, Create bulk draft hire — request body — body draft hires item personal info emergency contact phone
Create a new employee document — response body — items item documents item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A document to attach to a draft hire, referencing a pre-uploaded file. |
file_id | string | Required within parent | Id of a FileUploadTracker in ACTIVE status whose file should become a document on the hire |
name | string | Optional | Document name. Defaults to the uploaded file name when omitted. |
signature_date | string | Optional | Signature date in YYYY-MM-DD format. |
Create bulk draft hire — request body — body draft hires item custom fields item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Custom field information for a draft hire. Custom fields are associated with RoleWithCompany model. |
field_name | string | Required within parent | Name of the custom field |
field_value | object | Required within parent | Value of the custom field |
Create bulk draft hire — request body — body draft hires item employment info equity vesting schedule
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Equity vesting schedule |
_name | string | Optional | Name of the vesting schedule |
cliffMonths | integer | Optional | Number of cliff months before vesting begins |
company_id | string | Required within parent | Required company ID for the vesting schedule |
continuousVestingMonths | integer | Optional | Number of continuous vesting months |
percentageInitialVesting | number | Optional | Percentage of initial vesting as decimal Format: decimal |
spokeId | string | Optional | Spoke ID for the vesting schedule |
totalVestingMonths | integer | Optional | Total number of vesting months |
totalVestingYears | integer | Optional | Total number of vesting years |
vestingType | string | Optional | Type of vesting schedule |
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: rippling.rest_api.create_draft_hires. Catalog operation: create-draft-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: ["draft-hires.read-write"]
Provider entitlements: ["API_Tier_1"]
Pinned headers: {"Rippling-Api-Version": "2024-08-01"}