Update and Invite Employment

Overview

The next step in onboarding an employee is to invite the employee, but before you learn how to do that through Remote API, let's take a look at the update employment endpoint that lets you modify the employment creation.

Update employment

When an employment record is created, its initial employment_lifecycle_stage is employment_creation, as explained in the employment lifecycle stages. To move to the next stage, you need to update the employment record. Employment data can only be updated through the Remote API before an invitation is sent to the employee using the update employment endpoint.

An already created employment, that is not deleted can be updated at any time. Through this endpoint, you can modify all information submitted during the creation step as well as add additional details like home address, bank account details, emergency contact, etc. But once the onboarding process is complete, only limited employment details like emergency contact details can be modified. So, if you need to make changes to the employment record, make sure to do so before sending the invite.

ℹ️ Updates are blocked once the invitation has been sent because in certain cases, employees need to agree to the amendments made, for example, changes to their contract details, etc.

To make the required edits, simply make a patch request by passing the employment_id. When updating an employment, the following events are triggered depending on what change was made to the employment.

• employment.start_date.changed: Triggered when an employer changes an employment's starting date.
• employment.personal_information.updated: This event is triggered every time an employment's personal information is changed.
• employment.details.updated: Triggered when an employment's department or manager is updated.
• employment.account.updated: Triggered whenever an employment's email account is updated.

A few important points to keep in mind while using this endpoint:

• For created employment, you can update all basic parameters, onboarding tasks, as well as basic_information.
• For active employment, you can update manager information, emergency contact details, and address details using this endpoint.
• Before modifying country-specific data, we recommend calling the show form schema endpoint because a country's compliance requirements change frequently, which results in a change in required and returned fields.
• If you are using this endpoint to build an integration, make sure to dynamically collect the latest parameters for each country by calling the show form schema endpoint.
• Updating contractor's details via the API is not supported. Please reach out to your Remote contact for any assistance.

🧪 Sandbox testing:
While using the sandbox update employment endpoint, you can only edit the status of an employee.

Invite employee

Once all the required data has been added and modified, you can proceed with inviting the employee to start their onboarding. Once the invitation is sent from your end, the employee will receive an email from [email protected]. Upon receiving that email, the employee will begin their self-enrollment process, where they provide any missing details, such as home address, emergency contact, bank and other necessary information.

You can invite an employee is through the invite employment endpoint. Send the employment_id in the path params and on success, you will get a "status": "ok" response.

Show employment

After the invitation has been sent, if you want to check the status of the employment, you can call the show employment endpoint and focus on employment_lifecycle_stage and status fields.

{
	"data": {
    "employment": {
      ...,
      "employment_lifecycle_stage": "employee_self_enrollment",
      ...,
      "id": "9fb23136-bb7c-488a-b5dc-37d3b7c9033b",
      ...
      "status": "invited",
    }
	}
}

Congratulations! 🎉 You have successfully created and invited a new employee. Next up, you can set employment benefits for the created employment.