v1

latestOpenAPI 3.1.02026-07-242735131.1 MB

Sandbox

Create employment

Creates an employment without provisional_start_date validation.

This endpoint is only available in Sandbox and allows creating employments which provisional_start_date is in the past. This is especially helpful for:

Testing the Timeoff Balance endpoints
Testing the Offboarding endpoints
Testing features around probation periods

This endpoint will respond with a 404 outside of the Sandbox environment.

For creating an employment's parameters outside of testing purposes, use this Employment create endpoint

post/v1/sandbox/employments

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

basic_informationobject required

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.

bill_to_legal_entity_idstring

Id of the legal entity that should be billed for the employment. If omitted, falls back to engaged_by_legal_entity_id. For EOR and Contractor employments this may differ from engaged_by_legal_entity_id. For Global Payroll and Direct (HRIS) employments it must match engaged_by_legal_entity_id.

company_idstring

This optional field is deprecated.

country_codestring required

The ISO 3166-1 3-letter country code where the employee will be based (e.g., AUS, GBR, USA).

engaged_by_entity_slugstring

Deprecated alias for engaged_by_legal_entity_id. Use engaged_by_legal_entity_id instead.

engaged_by_legal_entity_idstring

Id of the legal entity that engages the employee or contractor. Required for Global Payroll employees. For EOR and Contractor employments this may differ from bill_to_legal_entity_id. For Global Payroll and Direct (HRIS) employments it must match bill_to_legal_entity_id.

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.

type'employee' | 'contractor' | 'global_payroll_employee' | 'hris'

If not provided, it will default to employee.

Example request

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

Response

Success

Example response

{
  "data": {
    "employment": {
      "basic_information": {
        "email": "jane@smith.com",
        "has_seniority_date": "no",
        "job_title": "Engineer",
        "name": "Jane Smith",
        "provisional_start_date": "2022-07-10",
        "work_email": "jane.smith@company.com"
      },
      "company_id": "20a72f86-company-id-20a72f86",
      "country_code": "AUS",
      "created_at": "2021-07-15T18:18:17Z",
      "employment_lifecycle_stage": "employment_creation",
      "full_name": "Jane Smith",
      "id": "663e0b79-c893-45ff-a1b2-f6dcabc098b5",
      "job_title": "Engineer",
      "login_email": "jane@smith.com",
      "personal_email": "jane@smith.com",
      "provisional_start_date": "2022-07-10",
      "type": "employee",
      "updated_at": "2021-07-15T18:18:17Z"
    }
  }
}