REremote-com
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

Authentication

This endpoint accepts any one of the following token types:

  • Company-scoped access token (OAuth2AuthorizationCode) — obtained by a company manager through the Authorization Code flow or the Refresh Token flow. See Authentication for partners.
  • Company-scoped access token (assertion) (OAuth2CompanyManagerAssertion) — obtained through the urn:ietf:params:oauth:grant-type:jwt-bearer grant for a company manager. See OAuth Assertion.
  • Customer API token (CustomerAPIToken) — generated by the customer on their Integration Settings page, with the scopes they choose there. See Authorization for customers.
post/v1/sandbox/employments

Request

  • Base URL
    https://gateway.remote.com
  • URL
    https://gateway.remote.com/v1/sandbox/employments
  • Auth
    • OAuth 2
      Authorization code: /auth/oauth2/authorize
      Token URL: /auth/oauth2/token
    • or OAuth 2
      Client credentials
      Token URL: /auth/oauth2/token
    • or HTTP bearer

Query parameters

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

An access token of one of the types listed in this endpoint's Authentication section, as Bearer <ACCESS TOKEN>.

A token from the Refresh Token flow is of the same type as the token issued with that refresh token.

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. At most 64 characters, counting any surrounding whitespace sent; that whitespace is then trimmed off. It can be set at any employment status, and the same value may be used on several employments (for example a rehire). See Your own IDs on Remote records.

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

No recorded changes to this operation across all 1 revision of this API.