Update employment

put

https://gateway.remote.com/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 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 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 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`)

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

employment_id

string

required

Employment ID

Query Params

address_details_json_schema_version

≥ 1

Version of the address_details form schema

administrative_details_json_schema_version

≥ 1

Version of the administrative_details form schema

bank_account_details_json_schema_version

≥ 1

Version of the bank_account_details form schema

employment_basic_information_json_schema_version

≥ 1

Version of the employment_basic_information form schema

billing_address_details_json_schema_version

≥ 1

Version of the billing_address_details form schema

contract_details_json_schema_version

≥ 1

Version of the contract_details form schema

emergency_contact_details_json_schema_version

≥ 1

Version of the emergency_contact_details form schema

personal_details_json_schema_version

≥ 1

Version of the personal_details form schema

pricing_plan_details_json_schema_version

≥ 1

Version of the pricing_plan_details form schema

skip_benefits

boolean

Skips the dynamic benefits part of the schema if set. To be used when benefits are set via its own API.

actions

string

Complementary action(s) to perform when creating an employment.

Body Params

Employment params

address_details

object

Home address information. As its properties may vary depending on the country, you must query the Show form schema 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 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 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 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 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 endpoint passing the country code and contract_details as path parameters.

country

object

A supported country on Remote

country_code

string

The ISO 3166-1 3-letter country code for this employment.

department_id

string | null

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 endpoint passing the country code and emergency_contact_details as path parameters.

external_id

string

length ≤ 64

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. 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 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 endpoint passing the country code and pricing_plan_details as path parameters.

type

string

enum

If not provided, it will default to employee.

Allowed:

work_email

string

The work email of the employment.

Headers

Authorization

string

required

Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.

The refresh token needs to have been obtained through the Authorization Code flow.

Responses

Callback

200Success

400Bad Request

403Forbidden

409Conflict

422Unprocessable Entity

429Unprocessable Entity