--- title: "Create employment" method: POST path: "/v1/sandbox/employments" tags: ["Sandbox"] --- # Create employment `POST /v1/sandbox/employments` ## Request - Base URL: `https://gateway.remote.com` - URL: `https://gateway.remote.com/v1/sandbox/employments` - Auth: one of: - OAuth 2 - Authorization code: `/auth/oauth2/authorize` - Token URL: `/auth/oauth2/token` - OAuth 2 - Client credentials - Token URL: `/auth/oauth2/token` - HTTP bearer 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](#operation/post_create_employment) ## 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](https://developer.remote.com/docs/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](https://developer.remote.com/docs/authorization-method-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](https://developer.remote.com/docs/authorization-for-customers). ## Query parameters - `group_tax_servicing_countries` boolean ## Headers - `Authorization` string, required ## Request body - EmploymentCreateParams: Description of the basic required and onboarding tasks params to create an employment. You do not need to include all onboarding tasks when creating or updating an employment. - `basic_information` object, required: Employment basic information. As its properties may vary depending on the country, you must query the [Show form schema](#tag/Countries/operation/get_show_form_country) endpoint passing the country code and `employment_basic_information` as path parameters. - `bill_to_legal_entity_id` string: 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_id` string: This optional field is deprecated. - `country_code` string, required: The ISO 3166-1 3-letter country code where the employee will be based (e.g., `AUS`, `GBR`, `USA`). - `engaged_by_entity_slug` string: Deprecated alias for `engaged_by_legal_entity_id`. Use `engaged_by_legal_entity_id` instead. - `engaged_by_legal_entity_id` string: 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_id` string: 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_id` string, 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](https://developer.remote.com/docs/your-own-ids-on-remote-records). - `type` 'employee' | 'contractor' | 'global_payroll_employee' | 'hris': If not provided, it will default to `employee`. ## Response `201` Success - EmploymentCreationResponse - `data` object - `employment` EmploymentBasicResponse: A lightweight employment representation returned after creation. Contains basic identification, country, and status fields but not the full onboarding details or country-specific form data. - `basic_information` object: Employment basic information. As its properties may vary depending on the country, you must query the [Show form schema](#tag/Countries/operation/get_show_form_country) endpoint passing the country code and `basic_information` as path parameters. When present, `login_email` indicates which address the employee logs in with: `"personal"` or `"work"`. - `company_id` string: The unique identifier (UUID) of the company. - `country_code` string: The ISO 3166-1 3-letter country code for this employment. - `created_at` string, date-time: When this employment was created. - `employment_lifecycle_stage` 'employment_creation' | 'employee_self_enrollment' | 'right_to_work_check' | 'contract_signing' | 'remote_enrollment' | 'onboarded' | 'offboarded': The stage of employment lifecycle. When it's `onboarded` means the employee is ready to commence or has already commenced. - `full_name` string: The employee's full name. - `id` string, uuid: A unique identifier in UUID v4 format. - `job_title` string, nullable: The employee's job title. May be null if not yet set. - `login_email` string, email: The email the employee uses to log in to Remote. - `partner_external_id` string, 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. Null when the integration has not set one. See [Your own IDs on Remote records](https://developer.remote.com/docs/your-own-ids-on-remote-records). - `personal_email` string, email: The employee's personal email address. - `provisional_start_date` string, date: Required for employees, optional for contractors - `type` 'employee' | 'contractor': The type of employment. - `updated_at` string, date-time: When this employment was last updated. ## Other responses - `400`: Bad Request - `401`: Unauthorized - `404`: Not Found - `422`: Unprocessable Entity - `429`: Too many requests --- [API](https://skmtc.dev/remote-com/apis/testing-sandbox.md) - [All operations](https://skmtc.dev/remote-com/apis/testing-sandbox/llms.txt) - [OpenAPI document](https://skmtc.dev/remote-com/apis/testing-sandbox/revisions/94f6859e2604?raw)