Employments
Employment Management

Update employment

Changed on

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)
patch/v2/employments/{employment_id}

Request

  • Base URL: https://gateway.remote.com
  • URL: https://gateway.remote.com/v2/employments/{employment_id}
  • 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)

Path parameters

employment_idstring required

Employment ID

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.

Request body

department_idstring nullable

The department of the employment. The department must belong to the same company as the employment. When set to null, the employment will be unassigned from a department.

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.

manager_idstring

The user id of the manager, who should have an admin, owner or people_manager role. You can find these users by querying the Company Managers endpoint.

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).

work_emailstring

The work email of the employment.

Example request

{
  "external_id": "ext-12345",
  "work_email": "jane.smith@company.com"
}

Response

Success

Example response

{
  "data": {
    "employment": {
      "personal_details": {},
      "manager_email": "john.doe@company.com",
      "provisional_start_date": "2021-07-03",
      "address_details": {},
      "pricing_plan_details": {
        "frequency": "annually"
      },
      "full_name": "Jane Smith",
      "type": "employee",
      "employment_lifecycle_stage": "employee_self_enrollment",
      "administrative_details": {},
      "company_id": "e31adae1-company-id-af5fba7dd803",
      "work_address_details": {},
      "bill_to_legal_entity_id": "663e0b79-c893-45ff-a1b2-f6dcabc098b5",
      "work_email": "jane.smith@company.com",
      "status": "created",
      "updated_at": "2021-07-15T18:18:17Z",
      "basic_information": {},
      "job_title": "Engineer",
      "id": "20a72f86-employment-id-9e4942a902ff",
      "manager": "John Doe",
      "login_email": "jane@smith.com",
      "employment_model": "eor",
      "personal_email": "jane@smith.com",
      "country": {
        "alpha_2_code": "PT",
        "code": "PRT",
        "contractor_products_available": [
          "standard",
          "plus",
          "cor"
        ],
        "country_subdivisions": [
          {
            "code": "PT-06",
            "name": "Coimbra",
            "subdivision_type": "District"
          },
          {
            "code": "PT-11",
            "name": "Lisboa",
            "subdivision_type": "District"
          }
        ],
        "employment_agreement_preview_available": true,
        "eor_onboarding": true,
        "global_payroll_supported": true,
        "locked_benefits": "after_first_hire",
        "name": "Portugal",
        "region": "Europe",
        "subregion": "Southern Europe",
        "supported_json_schemas": [
          "additional_documents",
          "address_details",
          "administrative_details",
          "employment-basic-information",
          "bank_account_details",
          "contract_details",
          "emergency_contact"
        ]
      },
      "user_status": "active",
      "bank_account_details": [],
      "files": [],
      "engaged_by_legal_entity_id": "663e0b79-c893-45ff-a1b2-f6dcabc098b5",
      "billing_address_details": {},
      "onboarding_tasks": {
        "address_details": {
          "description": "Primary residence.",
          "status": "completed"
        },
        "administrative_details": {
          "description": "Information we need for tax purposes.",
          "status": "completed"
        },
        "bank_account_details": {
          "description": "Bank account used for receiving salary payments.",
          "status": "completed"
        },
        "billing_address_details": {
          "description": "Address associated with the employee's bank account.",
          "status": "completed"
        },
        "contract_details": {
          "description": "Employee-specific details for their employment agreement.",
          "status": "completed"
        },
        "emergency_contact_details": {
          "description": "Who should be called in an emergency.",
          "status": "completed"
        },
        "employment_document_details": {
          "description": "We need some additional documents.",
          "status": "pending"
        },
        "personal_details": {
          "description": "Personal details, such as name and date of birth.",
          "status": "completed"
        },
        "pricing_plan_details": {
          "description": "How often Remote will bill employers for management fees.",
          "status": "completed"
        }
      },
      "contract_details": {},
      "emergency_contact_details": {},
      "eligible_for_onboarding_cancellation": true,
      "manager_employment_id": "20a72f86-employment-id-9e4942a902ff",
      "created_at": "2021-11-11T18:44:39"
    }
  }
}

Changes

  • 51aa6655a32fRevision changes
    • info

      added the new optional query request parameter group_tax_servicing_countries

    • info

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

  • 9410f5f18a91Revision changes
    • warning

      added the new invited enum value to the // response property for the response status