Rippling: Create hire — request body — body hires item

API reference · Contract 2026-10-28

SDK schema: Create hire — request body — body hires item

Field	Type	Presence	Description and constraints
$	object	Root	One hire on POST /hires/. Country-specific employment fields come from GET /hire-requirements/. Additional keys: not allowed
client_request_id	string	Optional	Optional id echoed on that hire’s result. Not a hire field.
compensation	object	Optional	Base pay and any additional compensation offered for this job. Monetary values contain an ISO 4217 currency code and decimal amount. Additional keys: not allowed
compensation.base_pay_amount	Model	Optional	Expand Create hire — request body — body hires item compensation base pay amount
compensation.base_pay_period	string	Optional	Unit of time represented by base_pay_amount: YEAR, MONTH, WEEK, DAY, or HOUR. For example, an annual salary uses YEAR and an hourly rate uses HOUR. Starting with API version 2025-08-01, contractor PAY_AS_YOU_GO compensation requires HOUR, MILESTONE requires YEAR, and FIXED accepts any listed unit. One of: YEAR, MONTH, WEEK, DAY, HOUR
compensation.commission	Model	Optional	Expand Create hire — request body — body hires item compensation commission
compensation.equity	Model	Optional	Expand Create hire — request body — body hires item compensation equity
compensation.relocation	Model	Optional	Expand Create hire — request body — body hires item compensation relocation
compensation.remote_working_allowance	object	Optional	Recurring allowance paid for remote-work expenses. Provide only when listed by GET /hire-requirements/ for the selected country and hire type; use a zero amount when the catalog requires the field but no allowance is offered.
compensation.remote_working_allowance.currency_type	string	Optional	The currency type, ex: USD, EUR, etc.
compensation.remote_working_allowance.value	number	Optional	The decimal amount for the currency.
compensation.signing_bonus	Model	Optional	Expand Create hire — request body — body hires item compensation signing bonus
compensation.target_bonus	Model	Optional	Expand Create hire — request body — body hires item compensation target bonus
compensation.thirteenth_month_bonus	object	Optional	Contractually required thirteenth-month salary payment. Provide only when listed by GET /hire-requirements/ for the selected country and hire type.
compensation.thirteenth_month_bonus.currency_type	string	Optional	The currency type, ex: USD, EUR, etc.
compensation.thirteenth_month_bonus.value	number	Optional	The decimal amount for the currency.
custom_fields	array	Optional	Values for company-configured custom fields collected during hiring. Use each field’s configured ID and value shape; omit this array when no custom hiring fields are being supplied.
custom_fields[]	Model	Each item	Expand Create hire — request body — body hires item custom fields item
employment	object	Required within parent	The job: title, hours, and country-specific details. Additional keys: not allowed
employment.authorized_to_work	boolean	Optional	Whether the person is legally authorized to work in the work_location country. Provide only when listed by GET /hire-requirements/; true confirms authorization and false may make the hire ineligible.
employment.collective_bargaining	Model	Optional	Expand Create hire — request body — body hires item employment collective bargaining
employment.company_uses_digital_currency	boolean	Optional	Whether the hiring company conducts business involving cryptocurrency or another digital currency. Required for China EOR hires. A true value may make the hire ineligible for the selected EOR service.
employment.contract	Model	Optional	Expand Create hire — request body — body hires item employment contract
employment.contractor_paying_entity_type	string	Optional	COMPANY_OWN_ENTITY hires the contractor on the company’s own legal entity. Send that entity in employment.legal_entity_id. Send this when the company is fully migrated to Global Payroll and the work location is in a Contractor of Record state. Omit for non-contractor hires. When the hiring flow requires it and it is omitted, the hire stays incomplete. One of: COMPANY_OWN_ENTITY
employment.department_id	string	Optional	Department id from GET /departments/.
employment.duties	string	Optional	Plain-text summary of the role’s primary responsibilities and day-to-day work.
employment.employment_model	string	Optional	Employment model for a Germany EOR hire. Use AUG for employee leasing or CONSULTANT for a remote consultant engagement. CONSULTANT is valid only when work_location.is_remote is true. One of: AUG, CONSULTANT
employment.employment_type_id	string	Required within parent	Employment type id from GET /employment-types/. Starting with API version 2025-08-01, a contractor employment type changes which fields are required or ignored. Call GET /hire-requirements/ for the applicable rules.
employment.engagement	object	Optional	Professional field and consulting-project details required by the hire context. Additional keys: not allowed
employment.engagement.consulting_project_description	string	Required within parent	Description of the client project and the work the worker will perform.
employment.engagement.field_of_work	string	Required within parent	Professional field in which the worker will perform the engagement.
employment.eor_costs_acknowledged	boolean	Optional	Confirms that the caller has reviewed and accepts the estimated EOR costs and applicable Rippling EOR terms for this hire. Required for EOR hires and must be true; false means the hire cannot proceed. See https://help.rippling.com/s/article/850659217136 and https://app.rippling.com/legal/eor.
employment.eor_eligibility_terms_acknowledged	boolean	Optional	Confirms that the caller has reviewed and accepts Rippling’s EOR eligibility conditions for this proposed hire, including the EOR screenout guidance. Required for EOR hires and must be true; false means the hire cannot proceed. See https://help.rippling.com/s/article/757822852718.
employment.framework_agreement	Model	Optional	Expand Create hire — request body — body hires item employment framework agreement
employment.french_occupation_classification_code	string	Optional	French Professions et Catégories Socioprofessionnelles (PCS) code that classifies the occupation performed by this role, such as 100X. Use a code allowed by GET /hire-requirements/.
employment.hired_due_to_merger	boolean	Optional	Required for GB and IE EOR. True if this hire is from a merger or acquisition.
employment.is_eor_transfer	boolean	Optional	Whether the worker’s employment is transferring from another employer-of-record provider. Send true for an EOR-to-EOR transfer and false when this is not an EOR transfer. Required for EOR hires outside the United States.
employment.is_shift_worker	boolean	Optional	Whether the role is legally or contractually classified as shift work, rather than merely having hours outside a typical workday. Send true when the applicable employment terms designate the worker as a shift worker; send false when they do not. Required only when listed by GET /hire-requirements/.
employment.is_technology_focused_role	boolean	Optional	Whether the role’s primary work is technology-focused. Required for China EOR hires when social_contribution_city is SHANGHAI or BEIJING; omit it for other cities.
employment.job_classification	string	Optional	US EEO-1 job category for the role. Use a value returned by GET /hire-requirements/. Omit for contractor hires.
employment.job_function_id	string	Optional	Job function that categorizes the type of work performed by this role. Send an id returned by GET /job-functions/.
employment.legal_entity_id	string	Optional	Send a candidate entity id from GET /company-legal-entities/. Required for direct_hire; omit for eor. Rippling validates that the selected entity belongs to the company and supports the requested hire.
employment.level_id	string	Optional	Job level for the role within the company’s job architecture. Send an id returned by GET /levels/.
employment.manager_id	string	Optional	Manager worker id from GET /workers/. Omit or null for no manager.
employment.meets_eor_eligibility_criteria	boolean	Optional	Confirms that the proposed hire satisfies Rippling’s country-specific EOR eligibility screening criteria. Required for Hong Kong, Switzerland, and New Zealand EOR hires and must be true. Rippling maps this assertion to the applicable country-specific screening response. See https://help.rippling.com/s/article/757822852718.
employment.modern_award	Model	Optional	Expand Create hire — request body — body hires item employment modern award
employment.non_compete	boolean	Optional	Whether the proposed employment terms include a non-compete restriction. Provide only when listed by GET /hire-requirements/.
employment.notice	Model	Optional	Expand Create hire — request body — body hires item employment notice
employment.overtime_classification	string	Optional	The role’s overtime classification under applicable employment law. EXEMPT means overtime requirements do not apply; NON_EXEMPT means the worker may be entitled to overtime pay. Omit for contractor hires. One of: EXEMPT, NON_EXEMPT
employment.owns_entity_in_country	boolean	Optional	Whether the hiring company owns a legal entity in the worker’s country. Required only when listed by GET /hire-requirements/; for Netherlands EOR hires, this answer determines the applicable hiring path.
employment.paid_sick_days	integer	Optional	Annual company-provided paid sick-day allowance, excluding any separate statutory entitlement. Provide only when listed by GET /hire-requirements/.
employment.probation	Model	Optional	Expand Create hire — request body — body hires item employment probation
employment.receives_tips	boolean	Optional	Whether the worker is expected to receive tips as part of this job. Omit for contractor hires.
employment.regular_working_hours	Model	Optional	Expand Create hire — request body — body hires item employment regular working hours
employment.requires_training	boolean	Optional	Whether the employment terms require the worker to complete training for this role. For Spanish direct hires, send true when training is required and false when it is not.
employment.schedule_type	string	Optional	The role’s recurring schedule pattern: FIXED_SCHEDULE for a consistent schedule or ROTATING_SHIFT_SCHEDULE for shifts that rotate. Provide only when listed by GET /hire-requirements/. One of: FIXED_SCHEDULE, ROTATING_SHIFT_SCHEDULE
employment.soc_code	string	Optional	US Standard Occupational Classification code for the job, such as 15-1252. Omit for contractor hires.
employment.social_contribution_city	string	Optional	Chinese city whose local social-insurance and statutory contribution rules apply to the worker, such as SHANGHAI or BEIJING. Required for China EOR hires. Use a value returned by GET /hire-requirements/.
employment.start_date	string	Optional	Start date in YYYY-MM-DD format.
employment.statutory_contract_classification	string	Optional	Country-specific statutory contract code. For Spain, use an allowed value returned by GET /hire-requirements/ that is compatible with contract.type and employment_type_id.
employment.statutory_job_classification	string	Optional	Statutory employment classification for the role. For Germany, choose the applicable value returned by GET /hire-requirements/, such as EMPLOYEE, APPRENTICE, WORKING_STUDENT, INTERN, MARGINALLY_EMPLOYED, SHORT_TERM_WORK, or MANAGING_DIRECTOR. Rippling derives the internal classification workflow from this value.
employment.supporting_documents	object	Optional	Employment documents required to prepare the hire. Additional keys: not allowed
employment.supporting_documents.resume_file_id	string	Optional	Id of the confirmed company-owned PDF or Word resume uploaded through POST /files/.
employment.supporting_documents.variable_compensation_plan_file_id	string	Optional	Id of the confirmed company-owned PDF or Word variable-compensation plan.
employment.team_ids	array	Optional	Teams the worker should belong to. Send team ids returned by GET /teams/. Omit for no team assignments.
employment.team_ids[]	string	Each item
employment.title	string	Required within parent	Job title.
employment.use_default_tenure	boolean	Optional	Set to true to start tenure on the start date. False keeps a prior tenure date unset.
employment.vacation	Model	Optional	Expand Create hire — request body — body hires item employment vacation
employment.vacation_rollover_days	integer	Optional	Maximum unused vacation days the worker may carry into the next leave year. Provide only when listed by GET /hire-requirements/.
employment.weekly_hours	string	Optional	Expected working hours per week. Supports whole or fractional hours, such as 40 or 37.5. Rippling derives any internal weekly-hours classification from this value. Omit for contractor hires.
employment.work_email	string	Optional	Work email for the hire.
employment.work_email_required	boolean	Optional	Set to false to skip work-email assignment for this hire, including generation by company policy. Do not combine false with a nonempty employment.work_email. Set to true to enable the normal work-email flow. For a newly created hire, true, omission, and null have the same behavior. Omission or null preserves any saved work-email preference. If related_records.existing_role_id identifies a hire that has already moved beyond creation, an explicit true or false can return that hire as incomplete with a validation error.
employment.worker_qualification	string	Optional	Worker’s professional qualification for a Switzerland EOR role, such as Engineer. This is plain text, not a Rippling resource identifier. Provide it only when GET /hire-requirements/ lists worker_qualification for the selected country and hire type.
employment.working_hours_arrangement	string	Optional	Working-hours system that legally applies to a China EOR role. Use STANDARD_WORKING_HOURS for a role governed by the standard daily and weekly limits, or FLEXIBLE_WORKING_HOURS when an approved flexible-hours system applies. Required for China EOR hires. One of: STANDARD_WORKING_HOURS, FLEXIBLE_WORKING_HOURS
employment.works_in_construction_industry	boolean	Optional	Whether the worker will perform work in Germany’s construction industry. Required for Germany EOR hires. Rippling EOR does not currently support these roles, so true makes the hire ineligible.
hire_type	string	Optional	Employment model for this hire: direct_hire employs the person through the company’s own legal entity; eor employs the person through Rippling’s employer-of-record service. Defaults to direct_hire when omitted.
personal	object	Optional	The person’s legal name and the email address or mobile number used to send their invitation. Additional keys: not allowed
personal.first_name	string	Optional	Person’s legal given name as it should appear on employment and payroll records.
personal.invite_email	string	Optional	Email address where the person should receive their Rippling invitation. At least one of invite_email or invite_phone is required; both may be provided.
personal.invite_phone	string	Optional	Mobile number where the person should receive their Rippling invitation, in international format including the country calling code, for example +14155550123. At least one of invite_email or invite_phone is required; both may be provided.
personal.last_name	string	Optional	Person’s legal family name as it should appear on employment and payroll records.
personal.nationality_code	string	Optional	Person’s nationality as an ISO 3166-1 alpha-2 country code, such as FR for French nationality. Provide it only when listed by GET /hire-requirements/. This is not the country where the person works.
related_records	Model	Optional	Expand Create hire — request body — body hires item related records
work_location	Model	Required within parent	Expand Create hire — request body — body hires item work location

Referenced models: Create hire — request body — body hires item custom fields item, Create hire — request body — body hires item compensation base pay amount, Create hire — request body — body hires item employment collective bargaining, Create hire — request body — body hires item compensation commission, Create hire — request body — body hires item employment contract, Create hire — request body — body hires item compensation equity, Create hire — request body — body hires item employment framework agreement, Create hire — request body — body hires item employment modern award, Create hire — request body — body hires item employment notice, Create hire — request body — body hires item employment probation, Create hire — request body — body hires item employment regular working hours, Create hire — request body — body hires item related records, Create hire — request body — body hires item compensation relocation, Create hire — request body — body hires item compensation signing bonus, Create hire — request body — body hires item compensation target bonus, Create hire — request body — body hires item employment vacation, Create hire — request body — body hires item work location