---
title: "Update employment"
method: PATCH
path: "/v1/employments/{employment_id}"
tags: ["Employment Management"]
---

# Update employment

`PATCH /v1/employments/{employment_id}`

Updates an employment.

**For `created` employments:** You can change all basic params and onboarding tasks or perform a per onboarding task update. You can also update basic_information.

**For `active` employments:** You can update the manager (`manager_id` field), emergency_contact_details, address_details and work_email.

**For `invited` employments:** You can update the work_email.

After onboarding, only a limited set of employment data will be available for updates, such as `emergency_contact_details`.
If you want to provide additional information for an employment, please make sure to do so **before** the employee is invited.
We block updates to some employment data because employees need to agree to amendments in certain cases, such as when there are changes to their contract_details.
Currently, these amendments can only be done through the Remote UI.

It is possible to update the `external_id` of the employment for all employment statuses.

## Global Payroll Employees

To update a Global Payment employment your input data must comply with the global payroll json schemas.

**For `active` employments:** In addition to the above list, you can update personal_details.

## Direct Employees

To update an HRIS employment your input data must comply with the HRIS json schemas.

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.


Please contact Remote if you need to update contractors via API since it's currently not supported.


## Scopes

| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employments (`employments`) | - | Manage employments (`employment:write`) |

## Path parameters

- `employment_id` string, required

## Query parameters

- `address_details_json_schema_version` union
  - integer — Specific version number
  - 'latest' — Use latest version
- `administrative_details_json_schema_version` union
  - integer — Specific version number
  - 'latest' — Use latest version
- `bank_account_details_json_schema_version` union
  - integer — Specific version number
  - 'latest' — Use latest version
- `employment_basic_information_json_schema_version` union
  - integer — Specific version number
  - 'latest' — Use latest version
- `billing_address_details_json_schema_version` union
  - integer — Specific version number
  - 'latest' — Use latest version
- `contract_details_json_schema_version` union
  - integer — Specific version number
  - 'latest' — Use latest version
- `emergency_contact_details_json_schema_version` union
  - integer — Specific version number
  - 'latest' — Use latest version
- `personal_details_json_schema_version` union
  - integer — Specific version number
  - 'latest' — Use latest version
- `pricing_plan_details_json_schema_version` union
  - integer — Specific version number
  - 'latest' — Use latest version
- `skip_benefits` boolean
- `actions` string

## Headers

- `Authorization` string, required

## Request body

- EmploymentFullParams — 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.
  - `address_details` object — Home address 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 `address_details` as path parameters.
  - `administrative_details` object — Administrative 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 `administrative_details` as path parameters.
  - `bank_account_details` object — Bank account 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 `bank_account_details` as path parameters.
  - `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 `employment_basic_information` as path parameters.
  - `billing_address_details` object — Billing address 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 `billing_address_details` as path parameters.
  - `company_id` string — The unique identifier (UUID) of the company. Optional when updating.
  - `contract_details` object — Contract 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 `contract_details` as path parameters.
  - `country` Country — A supported country on Remote
    - `alpha_2_code` string, required — The ISO 3166-1 alpha-2 country code (e.g., "PT").
    - `code` string, required — The ISO 3166-1 alpha-3 country code (e.g., "PRT"). This is the primary code used across the Remote API.
    - `contractor_products_available` string[] — Contractor product names available for this country
    - `country_subdivisions` CountrySubdivision[], nullable — Administrative subdivisions of the country (e.g., states, provinces, districts). Null if the country has no subdivisions relevant to Remote's services.
      - `code` string — The ISO 3166-2 subdivision code (e.g., "PT-11" for Lisboa).
      - `name` string, required — The subdivision's name (e.g., "Lisboa", "California").
      - `subdivision_type` string — The type of subdivision (e.g., "District", "State", "Province").
    - `employment_agreement_preview_available` boolean — Whether an Employment Agreement preview is available for this country.
    - `eor_onboarding` boolean — Whether EOR (Employer of Record) onboarding is available in this country.
    - `locked_benefits` string — When benefit plan selections become locked for this country (e.g., "after_first_hire" means benefits cannot be changed after the first employee is hired).
    - `name` string, required — The country's full English name.
    - `region` string — The geographic region the country belongs to (e.g., "Europe", "Asia", "Americas").
    - `subregion` string, nullable — The geographic subregion (e.g., "Southern Europe", "Southeast Asia"). Null for some countries.
    - `supported_json_schemas` string[] — The list of JSON schema form names available for this country (e.g., "address_details", "contract_details"). Use these with the Show form schema endpoint to get country-specific field requirements.
  - `country_code` string — The ISO 3166-1 3-letter country code for this employment.
  - `department_id` string, nullable — The department of the employment. The department must belong to the same company as the employment. When set to `null`, the employment will be unassigned from a department.
  - `emergency_contact_details` object — Emergency contact 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 `emergency_contact_details` as path parameters.
  - `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.
  - `manager_id` string — The user id of the manager, who should have an `admin`, `owner` or `people_manager` role. You can find these users by querying the [Company Managers endpoint](#operation/get_index_company_manager). **Update of this field is only available for active employments.**
  - `personal_details` object — Personal details 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 `personal_details` as path parameters.
  - `pricing_plan_details` object — Pricing plan details 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 `pricing_plan_details` as path parameters.
  - `type` 'employee' | 'contractor' — If not provided, it will default to `employee`.
  - `work_email` string — The work email of the employment.

## Response `200`

Success

- EmploymentResponse — Response containing the full employment record after an update operation.
  - `data` object, required
    - `employment` Employment — Complete information of an employment, including all onboarding task statuses, country-specific form data (address, contract, administrative, etc.), and contractor-specific settings where applicable.
      - `personal_details` object, required — Personal details information. Its properties may vary depending on the country.
      - `short_id` string — Unique short identifier for the employment, automatically generated and visible in select areas of the Remote platform. Not intended as a replacement for the employment `id` field.
      - `department` string, nullable — Name of related department, if any. Otherwise, null.
      - `manager_email` string, nullable, required — The email address of the employee's manager. Null if no manager is assigned.
      - `provisional_start_date` string, date — Indicates the expected start date of the employee or contractor. Required for employees, but optional for contractors. Date format is in ISO8601 without the time component. See the **Date and Time Format** documentation for more details on how the Remote API works with dates.
      - `address_details` object, required — Home address information. Its properties may vary depending on the country.
      - `pricing_plan_details` PricingPlanDetails, required — Selected type of payment.
        - `frequency` 'annually' | 'monthly', required — How often Remote bills the employer for management fees. Annual billing typically offers a discount.
      - `full_name` string, required — The employee's full name.
      - `type` 'employee' | 'contractor' | 'direct_employee' | 'global_payroll_employee', required — For the employment types `contractor`, `global_payroll_employee` and `direct_employee`, only [List employments](#operation/get_index_employment) and [Show employment](#operation/get_show_employment) operations are available.
      - `contractor_settings` object, nullable — Contractor-specific settings. Only present for contractor employments.
        - `requires_work_confirmation` boolean — Whether the contractor requires work confirmation before submitting invoices.
      - `employment_lifecycle_stage` 'employment_creation' | 'employee_self_enrollment' | 'right_to_work_check' | 'contract_signing' | 'remote_enrollment' | 'onboarded' | 'offboarded', required — The stage of employment lifecycle. When it's `onboarded` means the employee is ready to commence or has already commenced.
      - `administrative_details` object, required — Administrative information. Its properties may vary depending on the country.
      - `contractor_type` 'standard' | 'cor' | 'plus', nullable — Type of contractor product. Only present for contractor employments. 'standard' for Contractor Standard, 'cor' for Contractor of Record, 'plus' for Contractor Plus.
      - `contractor_rate` object, nullable — Contractor compensation rate details. Only present for contractor employments when rate is configured.
        - `amount` object
          - `amount` number — Rate amount as decimal
          - `currency` object
            - `code` string — Currency code (e.g., USD, EUR)
        - `pay_frequency` 'weekly' | 'bi_weekly' | 'semi_monthly' | 'monthly', nullable — Payment frequency cadence
        - `slug` string — Unique identifier for the contractor rate
        - `type` 'hourly' | 'daily' | 'weekly' | 'monthly' | 'one_off' — Rate type indicating billing frequency
      - `company_id` string, required — The unique identifier (UUID) of the company this employment belongs to.
      - `expiration_date` string, date, nullable — The planned service end date for contractor of record (COR) employments. For signed COR contractors, this date is stored on the contract record (not in `contract_details`). It is `null` for employee employments or unsigned contractor agreements. Date format is ISO 8601 without the time component (e.g. "2024-12-31").
      - `work_address_details` object, required — Work address information. Its properties may vary depending on the country.
      - `bill_to_legal_entity_id` string, uuid, nullable — The unique identifier (UUID) of the legal entity that is billed for this employment.
      - `work_email` string, required — The employee's work email address, typically provided by the employer.
      - `status` 'active' | 'created' | 'pre_hire' | 'created_awaiting_reserve' | 'created_reserve_paid' | 'initiated' | 'invited' | 'pending' | 'review' | 'job_title_review' | 'pending_post_self_enrollment_actions' | 'offboarding' | 'archived' | 'deleted', required — The current status of the employment record. - `active`: The employee is fully onboarded and actively working. - `created`: The employment has been created but onboarding has not started. - `pre_hire`: A pre-hire employment record, created before formal onboarding begins. - `created_awaiting_reserve`: The employment is created but waiting for a risk reserve deposit to be paid. - `created_reserve_paid`: The risk reserve has been paid and the employment can proceed with onboarding. - `initiated`: Onboarding has been started by the employer. - `invited`: The employee has been invited to complete their self-enrollment on Remote. - `pending`: The employment is pending review or further action before it can become active. - `review`: The employment is under review by Remote (e.g., contract or compliance review). - `archived`: The employment has been terminated or offboarded. - `deleted`: The employment record has been deleted.
      - `updated_at` string, date-time, required — The timestamp when this employment record was last updated.
      - `basic_information` object — Employment basic information. Its properties may vary depending on the country.
      - `job_title` string, nullable, required — The employee's job title. May be null if not yet set.
      - `id` string, required — The unique identifier (UUID) of the employment.
      - `probation_period_end_date` string, date — The date when the employee's probation period ends, if applicable.
      - `department_id` string, uuid, nullable — Unique ID of related department, if any. Otherwise, null.
      - `manager` string — The full name of the employee's manager.
      - `login_email` string, required — The email address the employee uses to log in to the Remote platform.
      - `external_id` string — A unique reference code for the employment record in a non-Remote system. While uniqueness is recommended, it is not strictly enforced within Remote's system.
      - `employment_model` 'global_payroll' | 'peo' | 'eor', nullable, required — For the employment models `peo` and `global_payroll`, only [List employments](#operation/get_index_employment) and [Show employment](#operation/get_show_employment) operations are available.
      - `personal_email` string, required — The employee's personal email address, used for account-related communications.
      - `country` NullableCountry, nullable, required — A supported country on Remote
        - `alpha_2_code` string, required — The ISO 3166-1 alpha-2 country code (e.g., "PT").
        - `code` string, required — The ISO 3166-1 alpha-3 country code (e.g., "PRT"). This is the primary code used across the Remote API.
        - `contractor_products_available` string[] — Contractor product names available for this country
        - `country_subdivisions` CountrySubdivision[], nullable — Administrative subdivisions of the country (e.g., states, provinces, districts). Null if the country has no subdivisions relevant to Remote's services.
          - `code` string — The ISO 3166-2 subdivision code (e.g., "PT-11" for Lisboa).
          - `name` string, required — The subdivision's name (e.g., "Lisboa", "California").
          - `subdivision_type` string — The type of subdivision (e.g., "District", "State", "Province").
        - `employment_agreement_preview_available` boolean — Whether an Employment Agreement preview is available for this country.
        - `eor_onboarding` boolean — Whether EOR (Employer of Record) onboarding is available in this country.
        - `locked_benefits` string — When benefit plan selections become locked for this country (e.g., "after_first_hire" means benefits cannot be changed after the first employee is hired).
        - `name` string, required — The country's full English name.
        - `region` string — The geographic region the country belongs to (e.g., "Europe", "Asia", "Americas").
        - `subregion` string, nullable — The geographic subregion (e.g., "Southern Europe", "Southeast Asia"). Null for some countries.
        - `supported_json_schemas` string[] — The list of JSON schema form names available for this country (e.g., "address_details", "contract_details"). Use these with the Show form schema endpoint to get country-specific field requirements.
      - `user_status` 'active' | 'created' | 'initiated' | 'cancelled' | 'inactive' | 'deleted' — The status of the user account associated with this employment. - `active`: The user account is active and the user can log in. - `created`: The user account has been created but not yet activated. - `initiated`: The user has been invited but has not completed registration. - `cancelled`: The user account was cancelled before activation. - `inactive`: The user account has been deactivated (e.g., after offboarding). - `deleted`: The user account has been deleted.
      - `seniority_date` string, date — The date the employee first started working for your company. If you don’t include a seniority date, the employee’s start date with Remote will be deemed as the start of the employee’s seniority. **Example**: Your employee started working for your company on Feb 1, 2022. On Aug 1, 2022, you transferred the employee to Remote and started managing them on the platform. Feb 1, 2022 would be their seniority date. Aug 1, 2022 would be their starting date.
      - `bank_account_details` object[], required
      - `files` File[], required — Documents associated with this employment (e.g., contracts, tax forms, identity documents).
        - `id` string, required — The unique identifier (UUID) of the file.
        - `inserted_at` string, date-time, required — UTC date time in [ISO 8601][] format. [ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601
        - `name` string, required — The file name including extension (e.g., "id.pdf", "contract.pdf").
        - `sub_type` string, nullable — A more specific classification of the file within its type (e.g., "personal_id" within type "id", or "ir_35" within type "contract"). Null if no sub-type applies.
        - `type` string, required — The broad category of the file (e.g., "id", "contract", "tax_form").
      - `active_contract_id` string — The unique identifier (UUID) of the currently active contract for this employment.
      - `engaged_by_legal_entity_id` string, uuid, nullable — The unique identifier (UUID) of the legal entity that engaged this employment.
      - `billing_address_details` object, required — Billing address information. Its properties may vary depending on the country.
      - `onboarding_tasks` OnboardingTasks, required — All tasks that need to be completed before marking the employment as ready
        - `address_details` TaskDescription, required — Description and status of an onboarding task.
          - `description` string — A human-readable description of what this onboarding task requires.
          - `status` 'completed' | 'pending' — The status of the task
        - `administrative_details` TaskDescription, required — Description and status of an onboarding task.
          - `description` string — A human-readable description of what this onboarding task requires.
          - `status` 'completed' | 'pending' — The status of the task
        - `bank_account_details` TaskDescription, required — Description and status of an onboarding task.
          - `description` string — A human-readable description of what this onboarding task requires.
          - `status` 'completed' | 'pending' — The status of the task
        - `billing_address_details` TaskDescription, required — Description and status of an onboarding task.
          - `description` string — A human-readable description of what this onboarding task requires.
          - `status` 'completed' | 'pending' — The status of the task
        - `contract_details` TaskDescription, required — Description and status of an onboarding task.
          - `description` string — A human-readable description of what this onboarding task requires.
          - `status` 'completed' | 'pending' — The status of the task
        - `emergency_contact_details` TaskDescription, required — Description and status of an onboarding task.
          - `description` string — A human-readable description of what this onboarding task requires.
          - `status` 'completed' | 'pending' — The status of the task
        - `employment_document_details` TaskDescription, required — Description and status of an onboarding task.
          - `description` string — A human-readable description of what this onboarding task requires.
          - `status` 'completed' | 'pending' — The status of the task
        - `personal_details` TaskDescription, required — Description and status of an onboarding task.
          - `description` string — A human-readable description of what this onboarding task requires.
          - `status` 'completed' | 'pending' — The status of the task
        - `pricing_plan_details` TaskDescription, required — Description and status of an onboarding task.
          - `description` string — A human-readable description of what this onboarding task requires.
          - `status` 'completed' | 'pending' — The status of the task
      - `contract_details` object, required — Contract information. Its properties may vary depending on the country.
      - `emergency_contact_details` object, required — Emergency contact information. Its properties may vary depending on the country.
      - `eligible_for_onboarding_cancellation` boolean, required — Whether this employment can still be cancelled during the onboarding process. Once the employment is active, this will be false.
      - `manager_employment_id` string, nullable, required — The employment ID of the employee's manager on Remote, if the manager is also managed through Remote. Null otherwise.
      - `created_at` string, required — The timestamp when this employment record was created.

## 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)