Sign in

v1

latestOpenAPI 3.1.02026-07-242735131.1 MB
Employment Management

Update employment

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

CategoryRead only ScopeWrite only Scope (read access implicit)
Manage employments (employments)-Manage employments (employment:write)
put/v1/employments/{employment_id}

Path parameters

employment_idstring required

Employment ID

Query parameters

integer

Specific version number

OR
'latest'

Use latest version

Version of the address_details form schema

integer

Specific version number

OR
'latest'

Use latest version

Version of the administrative_details form schema

integer

Specific version number

OR
'latest'

Use latest version

Version of the bank_account_details form schema

integer

Specific version number

OR
'latest'

Use latest version

Version of the employment_basic_information form schema

integer

Specific version number

OR
'latest'

Use latest version

Version of the billing_address_details form schema

integer

Specific version number

OR
'latest'

Use latest version

Version of the contract_details form schema

integer

Specific version number

OR
'latest'

Use latest version

Version of the emergency_contact_details form schema

integer

Specific version number

OR
'latest'

Use latest version

Version of the personal_details form schema

integer

Specific version number

OR
'latest'

Use latest version

Version of the pricing_plan_details form schema

skip_benefitsboolean

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

actionsstring

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

Headers

Authorizationstring 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.

Request body

address_detailsobject

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_detailsobject

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_detailsobject

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_informationobject

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_detailsobject

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_idstring

The unique identifier (UUID) of the company. Optional when updating.

contract_detailsobject

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_codestring

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

department_idstring 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_detailsobject

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_idstring

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_idstring

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_detailsobject

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_detailsobject

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'employee' | 'contractor'

If not provided, it will default to employee.

work_emailstring

The work email of the employment.

Example request

{
  "basic_information": {
    "email": "jane@smith.com",
    "name": "Jane Smith"
  },
  "company_id": "663e0b79-c893-45ff-a1b2-f6dcabc098b5",
  "country_code": "AUS",
  "work_email": "jane@smith.com"
}

Response

Success

Example response

{
  "data": {
    "employment": {
      "personal_details": {},
      "manager_email": "john.doe@company.com",
      "provisional_start_date": "2021-07-03",
      "address_details": {},
      "pricing_plan_details": {
        "frequency": "annually"
      },
      "full_name": "Jane Smith",
      "type": "employee",
      "employment_lifecycle_stage": "employee_self_enrollment",
      "administrative_details": {},
      "company_id": "e31adae1-company-id-af5fba7dd803",
      "work_address_details": {},
      "bill_to_legal_entity_id": "663e0b79-c893-45ff-a1b2-f6dcabc098b5",
      "work_email": "jane.smith@company.com",
      "status": "created",
      "updated_at": "2021-07-15T18:18:17Z",
      "basic_information": {},
      "job_title": "Engineer",
      "id": "20a72f86-employment-id-9e4942a902ff",
      "manager": "John Doe",
      "login_email": "jane@smith.com",
      "employment_model": "eor",
      "personal_email": "jane@smith.com",
      "country": {
        "alpha_2_code": "PT",
        "code": "PRT",
        "contractor_products_available": [
          "standard",
          "plus",
          "cor"
        ],
        "country_subdivisions": [
          {
            "code": "PT-06",
            "name": "Coimbra",
            "subdivision_type": "District"
          },
          {
            "code": "PT-11",
            "name": "Lisboa",
            "subdivision_type": "District"
          }
        ],
        "employment_agreement_preview_available": true,
        "eor_onboarding": true,
        "locked_benefits": "after_first_hire",
        "name": "Portugal",
        "region": "Europe",
        "subregion": "Southern Europe",
        "supported_json_schemas": [
          "additional_documents",
          "address_details",
          "administrative_details",
          "employment-basic-information",
          "bank_account_details",
          "contract_details",
          "emergency_contact"
        ]
      },
      "user_status": "active",
      "bank_account_details": [],
      "files": [],
      "engaged_by_legal_entity_id": "663e0b79-c893-45ff-a1b2-f6dcabc098b5",
      "billing_address_details": {},
      "onboarding_tasks": {
        "address_details": {
          "description": "Primary residence.",
          "status": "completed"
        },
        "administrative_details": {
          "description": "Information we need for tax purposes.",
          "status": "completed"
        },
        "bank_account_details": {
          "description": "Bank account used for receiving salary payments.",
          "status": "completed"
        },
        "billing_address_details": {
          "description": "Address associated with the employee's bank account.",
          "status": "completed"
        },
        "contract_details": {
          "description": "Employee-specific details for their employment agreement.",
          "status": "completed"
        },
        "emergency_contact_details": {
          "description": "Who should be called in an emergency.",
          "status": "completed"
        },
        "employment_document_details": {
          "description": "We need some additional documents.",
          "status": "pending"
        },
        "personal_details": {
          "description": "Personal details, such as name and date of birth.",
          "status": "completed"
        },
        "pricing_plan_details": {
          "description": "How often Remote will bill employers for management fees.",
          "status": "completed"
        }
      },
      "contract_details": {},
      "emergency_contact_details": {},
      "eligible_for_onboarding_cancellation": true,
      "manager_employment_id": "20a72f86-employment-id-9e4942a902ff",
      "created_at": "2021-11-11T18:44:39"
    }
  }
}