Employments
Employment Management

Create employment

Changed on

Creates an employment. We support creating employees and contractors.

Global Payroll Employees

To create a Global Payroll employee, pass global_payroll_employee as the type parameter, and provide the id of the specific legal entity that the employee will be engaged by and billed to as the engaged_by_legal_entity_id parameter.

HRIS Employees

To create a HRIS employee, pass hris as the type parameter.

Job Title Eligibility

When the company requires the job title eligibility check, an ineligible job_title is rejected here, before the employment or any contract details exist — not only when contract details are later submitted.

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.

Authentication

This endpoint accepts any one of the following token types:

  • Company-scoped access token (OAuth2AuthorizationCode) — obtained through the Authorization Code flow or the Refresh Token flow. See Authentication for partners.
  • Customer API token (CustomerAPIToken) — generated by the customer on their Integration Settings page. See Authorization for customers.

Scopes

CategoryRead only ScopeWrite only Scope (read access implicit)
Manage employments (employments)-Manage employments (employment:write)
post/v1/employments

Request

  • Base URL: https://gateway.remote.com
  • URL: https://gateway.remote.com/v1/employments
  • Auth: HTTP bearer and OAuth 2 (authorization code, authorization URL /auth/oauth2/authorize, token URL /auth/oauth2/token, scopes: https://gateway.remote.com/company.manage, employment:write, employments, all:write)

Query parameters

integer

Specific version number

OR
'latest'

Use latest version

Version of the form schema

group_tax_servicing_countriesboolean

When true, returns tax_servicing_countries grouped into global/regions/subregions instead of a flat list of country names.

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.

partner_external_idstring nullable

A reference code for the employment record in the calling integration's own system. Private to that integration — no other integration can read or overwrite it. Omit the field to leave the value unchanged; send null or an empty string to clear it. Surrounding whitespace is trimmed off. It can be set at any employment status, and the same value may be used on several employments (for example a rehire).

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",
        "login_email": "personal",
        "name": "Jane Smith",
        "personal_email": "jane@smith.com",
        "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"
    }
  }
}

Changes

  • 51aa6655a32fRevision changes
    • info

      added the new optional query request parameter group_tax_servicing_countries

  • 95bd07c1c768Revision changes
    • info

      added the new optional request property

    • info

      added the optional property // to the response with the status