Create Employment

Overview

After retrieving the JSON schema, you can call the create employment endpoint and submit the employment data to create a new employee. The employment you create will be associated with the company-scoped access token of the company for which you are setting up the employment.

Send the required fields gathered in the previous step as a JSON-encoded payload inside the basic_information object of the endpoint.

{
  "employment": {
  "basic_information": {
    "email": "[email protected]",
    "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",
  "external_id": "ext-12345-abc",
  "type": "employee"
  }
}

In this request,

• basic_information: includes an employee's basic data. The basic_information object may include additional dynamic fields based on the country, such as has_seniority_date. Because these fields vary depending on the country, using JSON schemas is essential to ensure each country's specific data requirements are met.
  • email: refers to the email address of the new employee.
  • has_seniority_date: indicates whether an employee started working for the company before being added to Remote.
  • job_title: refers to the title of the new employee in the company.
  • name: is the name of the employee.
  • provisional_start_date: refers to the official start date of the new employee.
• 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.
• external_id: refers to an optional external reference code for the employment, linking to non-Remote systems. Defaults to null if not provided. Uniqueness is recommended but not enforced by Remote.
• 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.

🧪 Sandbox testing:

• To test employment creation in a sandbox environment, use the create employment endpoint. It allows you to create an employment without the provisional_start_date validation, which means you can add a date that's in the past as well.
• When providing an email address in sandbox, it is recommended to use a unique, valid email that can receive messages. This allows you to verify that the employee is receiving emails as expected. If you are using Gmail, GSuite, or Outlook, you can create a unique email address by appending +randomtext to your own email address. For example, if your email address is [email protected], you can use [email protected] while testing employment creation in sandbox. This ensures uniqueness while still delivering emails to the same inbox.

With the above fields, you will get the following response:

{
  "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": "[email protected]",
      "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": "[email protected]"
      }
}

ℹ️ If your company-scoped access token has expired, you will receive an Unauthorized response. To obtain a new valid token, follow the refresh token flow.

When an employment is created, it goes through different stages. These stages are defined in the employment_lifecycle_stage field in the response. Learn more about these stages in the employment lifecycle stages section.

In the above response, you will notice status and user_status fields. Find a detailed breakdown of these fields in the employment and user statuses section.

Now that you have an employment, you can get started with its onboarding as explained in the next step.