--- title: "Create employment" method: POST path: "/v1/employments" tags: ["Employment Management"] --- # Create employment `POST /v1/employments` Creates an employment. We support creating employees and contractors. ## Global Payroll Employees To create a Global Payroll employee, pass `global_payroll_employee` as the `type` parameter, and provide the id of the specific legal entity that the employee will be engaged by and billed to as the `engaged_by_legal_entity_id` parameter. ## HRIS Employees To create a HRIS employee, pass `hris` as the `type` parameter. This endpoint requires and returns country-specific data. The exact required and returned fields will vary depending on which country the employment is in. To see the list of parameters for each country, see the **Show form schema** endpoint under the [Countries](#tag/Countries) category. Please note that the compliance requirements for each country are subject to change according to local laws. Given its continual updates, using Remote's [json-schema-form](https://developer.remote.com/docs/how-json-schemas-work) should be considered in order to avoid compliance issues and to have the latest version of a country requirements. If you are using this endpoint to build an integration, make sure you are dynamically collecting or displaying the latest parameters for each country by querying the _"Show form schema"_ endpoint. For more information on JSON Schemas, see the **How JSON Schemas work** documentation. To learn how you can dynamically generate forms to display in your UI, see the documentation for the [json-schema-form](https://developer.remote.com/docs/how-json-schemas-work) tool. ## Scopes | Category | Read only Scope | Write only Scope (read access implicit) | |---|---|---| | Manage employments (`employments`) | - | Manage employments (`employment:write`) | ## Query parameters - `json_schema_version` union - integer — Specific version number - 'latest' — Use latest version ## Headers - `Authorization` string, required ## Request body - EmploymentCreateParams — Description of the basic required and onboarding tasks params to create an employment. You do not need to include all onboarding tasks when creating or updating an employment. - `basic_information` object, required — Employment basic information. As its properties may vary depending on the country, you must query the [Show form schema](#tag/Countries/operation/get_show_form_country) endpoint passing the country code and `employment_basic_information` as path parameters. - `bill_to_legal_entity_id` string — Id of the legal entity that should be billed for the employment. If omitted, falls back to `engaged_by_legal_entity_id`. For EOR and Contractor employments this may differ from `engaged_by_legal_entity_id`. For Global Payroll and Direct (HRIS) employments it must match `engaged_by_legal_entity_id`. - `company_id` string — This optional field is deprecated. - `country_code` string, required — The ISO 3166-1 3-letter country code where the employee will be based (e.g., `AUS`, `GBR`, `USA`). - `engaged_by_entity_slug` string — Deprecated alias for `engaged_by_legal_entity_id`. Use `engaged_by_legal_entity_id` instead. - `engaged_by_legal_entity_id` string — Id of the legal entity that engages the employee or contractor. Required for Global Payroll employees. For EOR and Contractor employments this may differ from `bill_to_legal_entity_id`. For Global Payroll and Direct (HRIS) employments it must match `bill_to_legal_entity_id`. - `external_id` string — A unique reference code for the employment record in a non-Remote system. This optional field links to external data sources. If not provided, it defaults to `null`. While uniqueness is recommended, it is not strictly enforced within Remote's system. - `type` 'employee' | 'contractor' | 'global_payroll_employee' | 'hris' — If not provided, it will default to `employee`. ## Response `200` Success - EmploymentCreationResponse - `data` object - `employment` EmploymentBasicResponse — A lightweight employment representation returned after creation. Contains basic identification, country, and status fields but not the full onboarding details or country-specific form data. - `basic_information` object — Employment basic information. As its properties may vary depending on the country, you must query the [Show form schema](#tag/Countries/operation/get_show_form_country) endpoint passing the country code and `basic_information` as path parameters. - `company_id` string — The unique identifier (UUID) of the company. - `country_code` string — The ISO 3166-1 3-letter country code for this employment. - `created_at` string, date-time — When this employment was created. - `employment_lifecycle_stage` 'employment_creation' | 'employee_self_enrollment' | 'right_to_work_check' | 'contract_signing' | 'remote_enrollment' | 'onboarded' | 'offboarded' — The stage of employment lifecycle. When it's `onboarded` means the employee is ready to commence or has already commenced. - `full_name` string — The employee's full name. - `id` string, uuid — Identifier of the employment being terminated. - `job_title` string, nullable — The employee's job title. May be null if not yet set. - `login_email` string, email — The email the employee uses to log in to Remote. - `personal_email` string, email — The employee's personal email address. - `provisional_start_date` string, date — Required for employees, optional for contractors - `type` 'employee' | 'contractor' — The type of employment. - `updated_at` string, date-time — When this employment was last updated. ## Other responses - `400` — Bad Request - `403` — Forbidden - `409` — Conflict - `422` — Unprocessable Entity - `429` — Unprocessable Entity --- [API](https://skmtc.net/remote-com/apis/remote.md) · [All operations](https://skmtc.net/remote-com/apis/remote/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/remote-com/remote/revisions/7e6a0c61ac82/schema)