Onboarding Employment

The Remote API allows adding new employees and contractors to a company programmatically. However, it doesn't mean they are ready to start working after the creation operation is successful. There are a few steps between providing all the required information and getting the employment ready to commence.

Creating a new employment

You can create a new employment using the Create employment endpoint. A typical employment body looks like this:

{
  "employment": {
  "basic_information": {
    "email": "jane@smith.com",
    "has_seniority_date": "no",
    "job_title": "Engineer",
    "name": "Jane Smith",
    "provisional_start_date": "2022-07-10"
  },
  "company_id": "20a72f86-company-id-20a72f86",
  "country_code": "AUS",
  "created_at": "2023-02-01T15:42:03",
  "employment_lifecycle_stage": "employment_creation",
  "full_name": "Jane Smith",
  "id": "663e0b79-c893-45ff-a1b2-f6dcabc098b5",
  "job_title": "Engineer",
  "personal_email": "jane@smith.com",
  "provisional_start_date": "2022-07-10",
  "type": "employee",
  "updated_at": "2023-02-01T15:42:03"
  }
}

In this request,

• basic_information: includes an employee's basic data.
• company_id: corresponds to the unique company ID to which the employee needs to be added.
• country_code: indicates the country where the employee is located.
• created_at: marks the timestamp at which the new employment was created.
• employment_lifecycle_stage: (Refer to the detailed section below).
• provisional_start_date: refers to the official start date of the new employment.
• type: indicates the type of employment being created. The employment can be an employee or a contractor.

  ℹ️ For the employment types contractor, global_payroll_employee and direct_employee, only List employments and Show employment operations are available.

• updated_at: refers to the timestamp at which the employment was last updated.

Employment lifecycle stage

Below is a list of possible stages in the employment lifecycle, represented by the employment_lifecycle_stage field in the Employment resource of the Remote API.

• employment_creation: This is the initial stage when required fields are still missing. Employment data can be submitted once using Create employmentand later completed via Update employment. Once all required information is provided, the stage automatically advances to employment_self_enrollment.
• employment_self_enrollment: At this stage, the employee or contractor must log in to the Remote platform and complete the necessary forms, which vary by country. Some information can be pre-filled with the Update employment endpoint. Refer to the API specification for details.
• right_to_work_check: Remote verifies the employee's or contractor's work eligibility for the specified country. After passing this check, Remote will facilitate contract signing. There's no need for Remote API at this stage.
• contract_signing: Once self-enrollment (and, the right-to-work check, if applicable) is complete, the employee remains in this stage until both parties sign the Employment Agreement Contract. This process takes place outside of the Remote API with Remote assisting as needed.
• remote_enrollment: After contract signing is done, Remote handles benefits enrollment, payroll setup, and other administrative steps. No API action is required at this time. This is the final step before employment begins.
• onboarded: The employee is officially ready to start work.
• offboarded: The employment is archived, and the employee is offboarded.

ℹ️ The employment_creation is the only stage that requires data to be sent through the API. The other stages will move forward automatically based on the events that happen in the Remote Platform or taken by any party — company, employment, or Remote.

offboarded Stage: Specific Cases

The transition to the offboarded stage takes time, as it requires both the employment to be archived and the termination_date to be reached. Here are some edge cases:

• Employee initiated resignation after provisional_start_date:
  If the employee resigns through Remote's platform and their termination_date is after the provisional_start_date, the employment_lifecycle_stage remains onboarded until the termination_date is reached.
  Once this termination_date passes, the employment status changes to archived, and the lifecycle stage is updated to offboarded.
• Termination or resignation before provisional_start_date:
  If the employee is terminated or resigns before their provisional_start_date and has not started onboarding, Remote will delete the employee without triggering any webhooks.
  After deletion, API calls to the Employments endpoints will return a 404 response.

Post employment creation

When an employment is created, the employment goes through a few stages as well. Let's take a look at what an employment body looks like after creation:

{
  "employment": {
    "address_details": {},
    "administrative_details": {},
    "bank_account_details": [],
    "basic_information": {},
    "billing_address_details": {},
    "company_id": "e31adae1-company-id-af5fba7dd803",
    "contract_details": {},
    "country": {
      ...
    },
      "created_at": "2021-11-11T18:44:39",
      "eligible_for_onboarding_cancellation": true,
      "emergency_contact_details": {},
      "files": [],
      "full_name": "Jane Smith",
      "id": "20a72f86-employment-id-9e4942a902ff",
      "job_title": "Engineer",
      "manager": "John Doe",
      "manager_email": "john.doe@company.com",
      "manager_employment_id": "20a72f86-employment-id-9e4942a902ff",
      "onboarding_tasks": {
        ...
      },
        "provisional_start_date": "2021-07-03",
        "status": "created",
        "type": "employee",
        "updated_at": "2021-11-11T18:44:39",
        "user_status": "active",
        "work_email": "jane.smith@company.com"
      }
}

Here are some new fields that you will notice in this definition:

• status:
  Here is a list of all possible values represented by status in the employment API.
  • created: Indicates that the employment has been created. At this stage, employer can edit employee's data.
  • created_awaiting_reserve: Indicates that the employment has been created but Remote is waiting for a reserve payment before an employer can invite the employee.
  • created_reserve_paid: Indicates that the reserve payment has been paid by the employer.
  • invited: Indicates that the employee has been invited but didn't start the onboarding process. At this stage, employer can no longer make changes to the employee's contract details.
  • initiated: Indicates that the employee has started their onboarding.
    On completion of every onboarding task, the employment.onboarding_task.completed event is triggered.
  • review: Indicates that the employee has completed onboarding and are being reviewed by the Remote admin.
  • pending: Indicates that employment is missing necessary fields while onboarding.
  • active: Indicates that the employment is active. The status is set to active when all user tasks are completed and the user status is also active. (Learn more about user statuses in the section below).
    On active, the employment.onboarding.completed event is triggered.
  • archived: Indicates that the employment has been archived and no longer in use. When an employment is marked as archived, the user status changes to inactive.
  • deleted: Indicates that the employment has been soft deleted by the admin. Accounts are deleted at the request of the users. When this is done, the user will no longer appear on the team page.
• user_status:
  • created: Indicates that a user was creates but did not start the onboarding.
  • initiated: Indicates that a user has started their onboarding process.
  • active: Indicates that a user has completed onboarding. This status is achieved when all onboarding user tasks are completed and the corresponding employment has a status review, pending, active, or archived.
    The employment.user_status.activated webhook is triggered when a user status changes to active.
  • cancelled: Indicates that a user contract was canceled. At this stage, the user can still log in and access their data and documents.
  • deleted: Indicates that a user has been deleted and can no longer log into Remote platform. Deleted users do not show up on the people page but can be searched in the Users table by a Remote admin.
  • inactive: Indicates that a user was deactivated and their employment is suspended. At this stage, the user can still log into the platform to access their data and documents but their invoicing capabilities have been revoked. The employer can reactivate a user at any time.
    The employment.user_status.deactivated webhook is triggered every time a user status changes to inactive.

Updating an employment

An already created employment, that is not deleted can be updated using the Update employment endpoint. When updating an employment, the following events are triggered depending on what change was made to the employment.

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