--- updatedAt: 2026-05-27T21:29:34.000Z agentTools: projectIndex: https://developer.remote.com/llms.txt --- # Update employment Updates an employment. Use this endpoint to: - modify employment states for testing - Backdate employment start dates This endpoint will respond with a 404 outside of the Sandbox environment. `partner_external_id` cannot be updated here and is ignored if sent, like any other unsupported field. Set it with `PATCH /api/eor/v1/employments/{employment_id}` instead. For updating an employment's parameters outside of testing purposes, use [this Employment update endpoint](#operation/patch_update_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). # OpenAPI definition ```json { "components": { "schemas": { "Employment": { "description": "Complete information of an employment, including all onboarding task statuses, country-specific form data (address, contract, administrative, etc.), and contractor-specific settings where applicable.", "example": { "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" }, "properties": { "personal_details": { "description": "Personal details information. Its properties may vary depending on the country.", "type": "object" }, "short_id": { "$ref": "#/components/schemas/ShortId" }, "department": { "description": "Name of related department, if any. Otherwise, null.", "nullable": true, "type": "string" }, "manager_email": { "description": "The email address of the employee's manager. Null if no manager is assigned.", "nullable": true, "type": "string" }, "provisional_start_date": { "$ref": "#/components/schemas/ProvisionalStartDate" }, "address_details": { "description": "Home address information. Its properties may vary depending on the country.", "type": "object" }, "pricing_plan_details": { "$ref": "#/components/schemas/PricingPlanDetails" }, "full_name": { "description": "The employee's full name.", "type": "string" }, "partner_external_id": { "description": "A reference code for the employment record in the calling integration's own system.\nPrivate to that integration — no other integration can read or overwrite it.\nNull when the integration has not set one.\nSee [Your own IDs on Remote records](https://developer.remote.com/docs/your-own-ids-on-remote-records).\n", "nullable": true, "type": "string" }, "type": { "description": "For the employment types `contractor`, `global_payroll_employee` and `direct_employee`, only [List employments](#operation/get_index_employment) and\n[Show employment](#operation/get_show_employment) operations are available.\n", "enum": [ "employee", "contractor", "direct_employee", "global_payroll_employee" ], "type": "string" }, "contractor_settings": { "description": "Contractor-specific settings. Only present for contractor employments.", "nullable": true, "properties": { "charges_vat": { "description": "Whether the contractor charges VAT on their invoices. Set by the contractor. Only used for Contractor Management and Contractor Management Plus.", "type": "boolean" }, "requires_work_confirmation": { "description": "Whether the contractor requires work confirmation before submitting invoices.", "type": "boolean" } }, "type": "object" }, "employment_lifecycle_stage": { "$ref": "#/components/schemas/EmploymentLifecycleStage" }, "administrative_details": { "description": "Administrative information. Its properties may vary depending on the country.", "type": "object" }, "contractor_type": { "description": "Type of contractor product. Only present for contractor employments. 'standard' for Contractor Standard, 'cor' for Contractor of Record, 'plus' for Contractor Plus.", "enum": [ "standard", "cor", "plus" ], "nullable": true, "type": "string" }, "contractor_rate": { "description": "Contractor compensation rate details. Only present for contractor employments when rate is configured.", "nullable": true, "properties": { "amount": { "properties": { "amount": { "description": "Rate amount as decimal", "type": "number" }, "currency": { "properties": { "code": { "description": "Currency code (e.g., USD, EUR)", "type": "string" } }, "type": "object" } }, "type": "object" }, "pay_frequency": { "description": "Payment frequency cadence", "enum": [ "weekly", "bi_weekly", "semi_monthly", "monthly" ], "nullable": true, "type": "string" }, "slug": { "description": "Unique identifier for the contractor rate", "type": "string" }, "type": { "description": "Rate type indicating billing frequency", "enum": [ "hourly", "daily", "weekly", "monthly", "one_off" ], "type": "string" } }, "type": "object" }, "company_id": { "description": "The unique identifier (UUID) of the company this employment belongs to.", "type": "string" }, "expiration_date": { "description": "The planned service end date for contractor of record (COR) employments.\n\nFor signed COR contractors, this date is stored on the contract record (not in `contract_details`).\nIt is `null` for employee employments or unsigned contractor agreements.\n\nDate format is ISO 8601 without the time component (e.g. \"2024-12-31\").\n", "format": "date", "nullable": true, "type": "string" }, "work_address_details": { "description": "Work address information. Its properties may vary depending on the country.", "type": "object" }, "bill_to_legal_entity_id": { "description": "The unique identifier (UUID) of the legal entity that is billed for this employment.", "example": "663e0b79-c893-45ff-a1b2-f6dcabc098b5", "format": "uuid", "nullable": true, "title": "BillToLegalEntityID", "type": "string" }, "work_email": { "description": "The employee's work email address, typically provided by the employer.", "type": "string" }, "status": { "$ref": "#/components/schemas/EmploymentStatus" }, "updated_at": { "description": "The timestamp when this employment record was last updated.", "format": "date-time", "type": "string" }, "has_active_withdrawal_method": { "description": "Whether the contractor has at least one active withdrawal method (the deposit method their invoices\nare paid out to). Only present for contractor employments. Use it to warn before creating an\ninvoice schedule for a contractor who hasn't added one yet.\n", "type": "boolean" }, "basic_information": { "description": "Employment basic information. Its properties may vary depending on the country.\n\nWhen present, `login_email` indicates which address the employee logs in with:\n`\"personal\"` or `\"work\"`.\n", "type": "object" }, "job_title": { "description": "The employee's job title. May be null if not yet set.", "nullable": true, "type": "string" }, "id": { "description": "The unique identifier (UUID) of the employment.", "type": "string" }, "probation_period_end_date": { "description": "The date when the employee's probation period ends, if applicable.", "format": "date", "type": "string" }, "department_id": { "description": "Unique ID of related department, if any. Otherwise, null.", "example": "663e0b79-c893-45ff-a1b2-f6dcabc098b5", "format": "uuid", "nullable": true, "title": "DepartmentID", "type": "string" }, "manager": { "description": "The full name of the employee's manager.", "type": "string" }, "login_email": { "description": "The email address the employee uses to log in to the Remote platform.", "type": "string" }, "external_id": { "description": "A unique reference code for the employment record in a non-Remote system. While uniqueness is recommended, it is not strictly enforced within Remote's system.", "nullable": true, "type": "string" }, "employment_model": { "description": "For the employment models `peo` and `global_payroll`, only [List employments](#operation/get_index_employment) and\n[Show employment](#operation/get_show_employment) operations are available.\n", "enum": [ "global_payroll", "peo", "eor" ], "nullable": true, "type": "string" }, "personal_email": { "description": "The employee's personal email address, used for account-related communications.", "type": "string" }, "country": { "$ref": "#/components/schemas/NullableCountry" }, "user_status": { "$ref": "#/components/schemas/UserStatus" }, "seniority_date": { "$ref": "#/components/schemas/EmploymentSeniorityDate" }, "bank_account_details": { "items": { "description": "List of bank account information. Its properties may vary depending on the country.", "type": "object" }, "type": "array" }, "files": { "description": "Documents associated with this employment (e.g., contracts, tax forms, identity documents).", "items": { "$ref": "#/components/schemas/File" }, "type": "array" }, "active_contract_id": { "description": "The unique identifier (UUID) of the currently active contract for this employment.", "type": "string" }, "engaged_by_legal_entity_id": { "description": "The unique identifier (UUID) of the legal entity that engaged this employment.", "example": "663e0b79-c893-45ff-a1b2-f6dcabc098b5", "format": "uuid", "nullable": true, "title": "EngagedByLegalEntityID", "type": "string" }, "billing_address_details": { "description": "Billing address information. Its properties may vary depending on the country.", "type": "object" }, "onboarding_tasks": { "$ref": "#/components/schemas/OnboardingTasks" }, "contract_details": { "description": "Contract information. Its properties may vary depending on the country.", "type": "object" }, "emergency_contact_details": { "description": "Emergency contact information. Its properties may vary depending on the country.", "type": "object" }, "eligible_for_onboarding_cancellation": { "description": "Whether this employment can still be cancelled during the onboarding process. Once the employment is active, this will be false.", "type": "boolean" }, "manager_employment_id": { "description": "The employment ID of the employee's manager on Remote, if the manager is also managed through Remote. Null otherwise.", "nullable": true, "type": "string" }, "created_at": { "description": "The timestamp when this employment record was created.", "type": "string" } }, "required": [ "address_details", "administrative_details", "bank_account_details", "billing_address_details", "company_id", "contract_details", "country", "created_at", "emergency_contact_details", "files", "full_name", "id", "type", "employment_model", "work_address_details", "job_title", "manager_email", "manager_employment_id", "onboarding_tasks", "personal_details", "personal_email", "login_email", "pricing_plan_details", "status", "employment_lifecycle_stage", "updated_at", "work_email", "eligible_for_onboarding_cancellation" ], "title": "Employment", "type": "object" }, "ActionError": { "properties": { "action": { "description": "The action that lead to the error message.", "type": "string" }, "code": { "description": "An error code that describes the nature of the error.", "type": "string" }, "message": { "description": "A developer friendly error message that gives details on what the error was and how it may be remedied.", "type": "string" } }, "required": [ "code", "message", "action" ], "title": "ActionError", "type": "object" }, "UserStatus": { "description": "The status of the user account associated with this employment.\n\n- `active`: The user account is active and the user can log in.\n- `created`: The user account has been created but the user hasn't been invited yet.\n- `invited`: The user has been invited but has not accepted the invitation yet.\n- `initiated`: The user has been invited but has not completed registration.\n- `cancelled`: The user account was cancelled before activation.\n- `inactive`: The user account has been deactivated (e.g., after offboarding).\n- `deleted`: The user account has been deleted.\n", "enum": [ "active", "created", "invited", "initiated", "cancelled", "inactive", "deleted" ], "example": "active", "title": "UserStatus", "type": "string" }, "NotFoundResponse": { "description": "Returned when the requested resource does not exist or is not accessible with the current authentication credentials.", "example": { "message": "{resource} not found" }, "properties": { "message": { "description": "A message indicating which resource was not found.", "pattern": "Not Found", "type": "string" } }, "title": "NotFoundResponse", "type": "object" }, "File": { "additionalProperties": false, "description": "A file associated with an employment, such as a contract, tax document, or identity document.", "example": { "id": "9880b711-file-id-ecf8f551bd78", "inserted_at": "2021-07-15T18:18:17Z", "name": "id.pdf", "sub_type": "personal_id", "type": "id" }, "properties": { "id": { "description": "The unique identifier (UUID) of the file.", "type": "string" }, "inserted_at": { "$ref": "#/components/schemas/DateTimeIso8601" }, "name": { "description": "The file name including extension (e.g., \"id.pdf\", \"contract.pdf\").", "type": "string" }, "sub_type": { "description": "A more specific classification of the file within its type (e.g., \"personal_id\" within type \"id\", or \"ir_35\" within type \"contract\"). Null if no sub-type applies.", "nullable": true, "type": "string" }, "type": { "description": "The broad category of the file (e.g., \"id\", \"contract\", \"tax_document\").", "type": "string" } }, "required": [ "id", "inserted_at", "name", "type" ], "title": "File", "type": "object" }, "ShortId": { "description": "Unique short identifier for the employment, automatically generated and visible in select areas of the Remote platform. Not intended as a replacement for the employment `id` field.", "example": "WN1IZT", "title": "ShortId", "type": "string" }, "UnprocessableEntityResponse": { "anyOf": [ { "properties": { "errors": { "type": "object" } }, "required": [ "errors" ], "type": "object" }, { "properties": { "message": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/ParameterError" }, { "items": { "$ref": "#/components/schemas/ParameterError" }, "title": "ParameterErrors", "type": "array" }, { "$ref": "#/components/schemas/ActionError" }, { "items": { "$ref": "#/components/schemas/ActionError" }, "title": "ActionErrors", "type": "array" } ] } }, "required": [ "message" ], "type": "object" } ], "example": { "errors": { "some_field": [ "is invalid" ] } }, "title": "UnprocessableEntityResponse", "type": "object" }, "EmploymentSeniorityDate": { "description": "The date the employee first started working for your company. If you don’t include a seniority date,\nthe employee’s start date with Remote will be deemed as the start of the employee’s seniority.\n\n**Example**: Your employee started working for your company on Feb 1, 2022.\nOn Aug 1, 2022, you transferred the employee to Remote and started managing them on the platform.\nFeb 1, 2022 would be their seniority date. Aug 1, 2022 would be their starting date.\n", "example": "2022-03-21", "format": "date", "title": "EmploymentSeniorityDate", "type": "string" }, "EmploymentUpdateParams": { "additionalProperties": false, "description": "Required params to update an employment in the Sandbox environment.\n\nCurrently supports setting the Employment Status to `active` and backdating the employment start date.\n\nAll fields other than the ones listed are ignored.\n", "example": { "provisional_start_date": "2024-01-01", "status": "active" }, "properties": { "provisional_start_date": { "format": "date", "type": "string" }, "status": { "$ref": "#/components/schemas/EmploymentStatus" } }, "title": "EmploymentUpdateParams", "type": "object" }, "ProvisionalStartDate": { "description": "Indicates the expected start date of the employee or contractor.\n\nRequired for employees, but optional for contractors. Date format is in ISO8601 without the time component.\n\nSee the **Date and Time Format** documentation for more details on how the Remote API works with dates.\n", "example": "2022-03-21", "format": "date", "title": "ProvisionalStartDate", "type": "string" }, "TaskDescription": { "description": "Description and status of an onboarding task.", "example": { "description": "Information we need for tax purposes.", "status": "completed" }, "properties": { "description": { "description": "A human-readable description of what this onboarding task requires.", "type": "string" }, "status": { "description": "The status of the task", "enum": [ "completed", "pending" ], "example": "completed", "title": "TaskStatus", "type": "string" } }, "title": "TaskDescription", "type": "object" }, "CountrySubdivision": { "description": "A subdivision of a supported country on Remote", "example": { "code": "PT-11", "name": "Lisboa", "subdivision_type": "District" }, "properties": { "code": { "description": "The ISO 3166-2 subdivision code (e.g., \"PT-11\" for Lisboa).", "type": "string" }, "name": { "description": "The subdivision's name (e.g., \"Lisboa\", \"California\").", "type": "string" }, "subdivision_type": { "description": "The type of subdivision (e.g., \"District\", \"State\", \"Province\").", "type": "string" } }, "required": [ "name" ], "title": "CountrySubdivision", "type": "object" }, "EmploymentLifecycleStage": { "description": "The stage of employment lifecycle. When it's `onboarded` means the employee is ready to commence or has already commenced.", "enum": [ "employment_creation", "employee_self_enrollment", "right_to_work_check", "contract_signing", "remote_enrollment", "onboarded", "offboarded" ], "example": "employee_self_enrollment", "title": "EmploymentLifecycleStage", "type": "string" }, "NullableCountry": { "description": "A supported country on Remote", "example": { "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" ] }, "nullable": true, "properties": { "alpha_2_code": { "description": "The ISO 3166-1 alpha-2 country code (e.g., \"PT\").", "type": "string" }, "code": { "description": "The ISO 3166-1 alpha-3 country code (e.g., \"PRT\"). This is the primary code used across the Remote API.", "type": "string" }, "contractor_products_available": { "description": "Contractor product names available for this country", "items": { "enum": [ "standard", "plus", "cor" ], "type": "string" }, "type": "array" }, "country_subdivisions": { "description": "Administrative subdivisions of the country (e.g., states, provinces, districts). Null if the country has no subdivisions relevant to Remote's services.", "items": { "$ref": "#/components/schemas/CountrySubdivision" }, "nullable": true, "type": "array" }, "employment_agreement_preview_available": { "description": "Whether an Employment Agreement preview is available for this country.", "type": "boolean" }, "eor_onboarding": { "description": "Whether EOR (Employer of Record) onboarding is available in this country.", "type": "boolean" }, "global_payroll_supported": { "description": "Whether Global Payroll employments can be onboarded in this country. When true, the \"global_payroll_administrative_details\", \"global_payroll_contract_details\" and \"global_payroll_personal_details\" forms are available from the Show form schema endpoint.", "type": "boolean" }, "locked_benefits": { "description": "When benefit plan selections become locked for this country (e.g., \"after_first_hire\" means benefits cannot be changed after the first employee is hired).", "type": "string" }, "name": { "description": "The country's full English name.", "type": "string" }, "region": { "description": "The geographic region the country belongs to (e.g., \"Europe\", \"Asia\", \"Americas\").", "type": "string" }, "subregion": { "description": "The geographic subregion (e.g., \"Southern Europe\", \"Southeast Asia\"). Null for some countries.", "nullable": true, "type": "string" }, "supported_json_schemas": { "description": "The list of JSON schema form names available for this country (e.g., \"address_details\", \"contract_details\", \"global_payroll_contract_details\"). Use these with the Show form schema endpoint to get country-specific field requirements.", "items": { "type": "string" }, "type": "array" } }, "required": [ "alpha_2_code", "code", "name" ], "title": "NullableCountry", "type": "object" }, "OnboardingTasks": { "description": "All tasks that need to be completed before marking the employment as ready", "example": { "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" } }, "properties": { "address_details": { "$ref": "#/components/schemas/TaskDescription" }, "administrative_details": { "$ref": "#/components/schemas/TaskDescription" }, "bank_account_details": { "$ref": "#/components/schemas/TaskDescription" }, "billing_address_details": { "$ref": "#/components/schemas/TaskDescription" }, "contract_details": { "$ref": "#/components/schemas/TaskDescription" }, "emergency_contact_details": { "$ref": "#/components/schemas/TaskDescription" }, "employment_document_details": { "$ref": "#/components/schemas/TaskDescription" }, "personal_details": { "$ref": "#/components/schemas/TaskDescription" }, "pricing_plan_details": { "$ref": "#/components/schemas/TaskDescription" } }, "required": [ "address_details", "administrative_details", "bank_account_details", "billing_address_details", "contract_details", "emergency_contact_details", "employment_document_details", "personal_details", "pricing_plan_details" ], "title": "OnboardingTasks", "type": "object" }, "EmploymentStatus": { "description": "The current status of the employment record.\n\n- `active`: The employee is fully onboarded and actively working.\n- `created`: The employment has been created but onboarding has not started.\n- `pre_hire`: A pre-hire employment record, created before formal onboarding begins.\n- `created_awaiting_reserve`: The employment is created but waiting for a risk reserve deposit to be paid.\n- `created_reserve_paid`: The risk reserve has been paid and the employment can proceed with onboarding.\n- `initiated`: Onboarding has been started by the employer.\n- `invited`: The employee has been invited to complete their self-enrollment on Remote.\n- `pending`: The employment is pending review or further action before it can become active.\n- `review`: The employment is under review by Remote (e.g., contract or compliance review).\n- `job_title_review`: The job title is pending verification by Remote; once approved, the employment returns to `created`.\n- `pending_post_self_enrollment_actions`: Self-enrollment is complete, but some actions are still missing before the employment can be activated.\n- `archived`: The employment has been terminated or offboarded.\n- `deleted`: The employment record has been deleted.\n", "enum": [ "active", "created", "created_awaiting_reserve", "created_reserve_paid", "initiated", "invited", "pending", "pre_hire", "review", "job_title_review", "pending_post_self_enrollment_actions", "archived", "deleted" ], "example": "active", "title": "EmploymentStatus", "type": "string" }, "TooManyRequestsResponse": { "description": "Returned when the API rate limit has been exceeded (HTTP 429). Wait before retrying. Check the `Retry-After` response header for the recommended wait time.", "example": { "message": "Too many requests" }, "properties": { "message": { "pattern": "Too many requests", "type": "string" } }, "title": "TooManyRequestsResponse", "type": "object" }, "ConflictResponse": { "description": "Returned when the request conflicts with the current state of a resource (HTTP 409). For example, trying to create a resource that already exists or performing an action that requires the resource to be in a different state.", "example": { "message": "Company needs to be in status active to manage employments" }, "properties": { "message": { "description": "A human-readable message describing the conflict and the expected state.", "type": "string" } }, "title": "ConflictResponse", "type": "object" }, "BadRequestResponse": { "description": "Returned when the request is malformed or contains invalid parameters. The message may be a simple string or a structured object with a code and detailed message.", "example": { "message": "invalid {resource}" }, "oneOf": [ { "properties": { "message": { "description": "A human-readable error message describing what was wrong with the request.", "type": "string" } }, "required": [ "message" ], "type": "object" }, { "properties": { "message": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "type": "object" } ], "title": "BadRequestResponse", "type": "object" }, "UnauthorizedResponse": { "description": "Returned when the request does not include valid authentication credentials. Ensure you are passing a valid OAuth2 access token or API token in the Authorization header.", "example": { "message": "Unauthorized" }, "properties": { "message": { "pattern": "Unauthorized", "type": "string" } }, "required": [ "message" ], "title": "UnauthorizedResponse", "type": "object" }, "PricingPlanDetails": { "description": "Selected type of payment.", "example": { "frequency": "annually" }, "properties": { "frequency": { "description": "How often Remote bills the employer for management fees. Annual billing typically offers a discount.", "enum": [ "annually", "monthly" ], "type": "string" } }, "required": [ "frequency" ], "title": "PricingPlanDetails", "type": "object" }, "DateTimeIso8601": { "description": "UTC date time in [ISO 8601][] format.\n\n[ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601\n", "example": "2021-07-15T18:18:17Z", "format": "date-time", "title": "DateTimeIso8601", "type": "string" }, "ParameterError": { "example": { "code": "invalid_param", "message": "Invalid parameter", "param": "employment_id" }, "properties": { "code": { "description": "An error code that describes the nature of the error.", "type": "string" }, "message": { "description": "A developer friendly error message that gives details on what the error was and how it may be remedied.", "type": "string" }, "param": { "description": "The parameter that lead to the error message.", "type": "string" } }, "required": [ "code", "message", "param" ], "title": "ParameterError", "type": "object" }, "EmploymentResponse": { "description": "Response containing the full employment record after an update operation.", "example": { "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" } } }, "properties": { "data": { "properties": { "employment": { "$ref": "#/components/schemas/Employment" } } } }, "required": [ "data" ], "title": "EmploymentResponse", "type": "object" } }, "securitySchemes": { "CustomerAPIToken": { "description": "Authenticate using API Key generated by the customer in their Integration Settings page.\n", "scheme": "bearer", "type": "http" }, "OAuth2": { "description": "Authenticate using OAuth 2.0 protocol.\n", "flows": { "authorizationCode": { "authorizationUrl": "/auth/oauth2/authorize", "scopes": { "company_department:read": "View departments: Read and list company departments", "webhook:write": "Manage webhooks: Set webhook callbacks and replay webhooks", "magic_link:write": "Create magic links: Create magic links", "offboarding:write": "Manage offboarding: Creates offboarding requests", "custom_field:write": "Manage custom fields: Create custom fields", "address:write": "Manage addresses: Create and update employee residential address", "expense:read": "View expenses: List and read expenses", "employment:write": "Manage employments: Create and update employments", "identity_verification:write": "Manage identity verification: Write identity verification data", "timesheet:write": "Manage timesheets: Create timesheets", "travel_letter:write": "Manage travel letters: Create travel letters", "all:read": "Read only: List and retrieve information about all resources", "incentive:read": "View incentives: List incentives and recurring incentives", "personal_detail:read": "View personal details: Read employee personal information", "invoices:write": "Manage invoices: Create invoices", "work_authorization:write": "Manage work authorizations: Create work authorization requests", "timeoff:write": "Manage timeoffs: Create, update and cancel timeoffs", "company_structure:read": "View company structure: Show company structure", "benefit_renewal:write": "Manage benefit renewals: Update benefit renewal requests", "benefit_offer:read": "View benefit offers: List benefit offers", "employment_documents": "Manage employment documents: Manage employment documents", "onboarding:write": "Manage onboarding: Cancel onboarding", "https://gateway.remote.com/company.manage": "Legacy scope. A new request for it gets `all:write`; tokens authorized before late March 2026 may still hold it. Many endpoints accept it, but not all: see the endpoint's `security` in the OpenAPI file", "project:write": "Manage projects: Create and update company projects and their leads and team members", "pay_in_details:read": "View pay-in details: Read the payment reference and Remote's bank details for paying contractor invoices", "payroll_run:read": "View payroll runs: List and show payroll runs", "risk_reserve:write": "Manage risk reserves: Create risk reserves for a company", "invoices": "Manage invoices: Manage invoices", "resignation_letter:read": "View resignation letters: Read resignation letters", "resignation:read": "View resignations: Read resignation requests", "convert_currency:read": "Convert currencies: Convert currencies", "all:write": "Full Access: Grant access to all scopes based on your current role permissions", "https://gateway.remote.com/employment.manage": "Legacy scope. A new request for it gets `all:write`; tokens authorized before late March 2026 may still hold it. Many endpoints accept it, but not all: see the endpoint's `security` in the OpenAPI file", "employments": "Manage employments: Create and manage employments", "probation_document:read": "View probation documents: Read probation completion letters and probation extensions documents", "company_admin": "Manage company resources: Create and manage company resources", "payroll": "Manage payroll runs: Manage payroll runs and calendars", "help_center_article:read": "View help articles: Read help center articles", "timesheet:read": "View timesheets: Read timesheets", "custom_field_value:write": "Manage custom field values: Create custom field values", "company_currencies:read": "View company currencies: List company supported currencies", "payslip:read": "View payslips: List and show employee's payslip", "pay_item:write": "Manage pay items: Create pay items for employments", "resignation:write": "Manage resignations: Validate resignation requests", "custom_field:read": "View custom fields: List custom fields", "payroll_calendar:read": "View payroll calendars: List payroll calendars", "contract_amendment:write": "Manage contract amendments: Create contract amendments", "offboarding:read": "View offboarding requests: Read and list offboarding requests", "timeoff:read": "View timeoffs: Read and list timeoffs", "pay_in_details": "View pay-in bank details: Read the payment reference and Remote's receiving bank accounts for paying invoices", "probation_document:write": "Manage probation documents: Create probation completion letters and probation extensions documents", "country:read": "View countries: Read and list countries", "webhook:read": "View webhooks: Read webhooks callback logs", "company_department:write": "Manage departments: Create company departments", "company_manager:read": "View managers: Read and list company managers", "pay_item:read": "View pay items: List pay items for employments", "contract_amendment:read": "View contract amendments: List and show contract amendments", "company:read": "View companies: Read and list companies", "sso_configuration:write": "Manage SSO: Set SSO configuration", "benefit_offer:write": "Manage benefit offers: Create benefit offers", "contract_eligibility:write": "Manage contract eligibility: Create contract eligibility for an employment", "benefit_renewal:read": "View benefit renewals: List benefit renewal requests", "background_check:read": "View background checks: Read and show background check requests", "custom_field_value:read": "View custom field values: List custom field values", "expense:write": "Manage expenses: Create expenses", "identity_verification:read": "View identity verification: Read identity verification data", "address:read": "View addresses: Read employee residential address", "document:write": "Manage documents: Write and update documents", "time_and_attendance": "Manage timeoffs: Manage timeoffs, leave-policies and timesheets", "employment_payments": "Manage expenses: Manage expenses and incentives", "form:read": "View forms: Read json schema forms", "work_authorization:read": "View work authorizations: List work authorization requests", "invoices:read": "View invoices: Read and list invoices", "incentive:write": "Manage incentives: Create incentives", "employment:read": "View employments: List and read employments", "contract:read": "View contracts: List employment contracts", "projects": "Manage projects: Create and manage company projects and their leads and team members", "company_manager:write": "Manage managers: Create and delete company managers", "travel_letter:read": "View travel letters: Read travel letters", "project:read": "View projects: List and read company projects", "document:read": "View documents: Read and list documents", "sso_configuration:read": "View SSO configuration: Read SSO configuration" }, "tokenUrl": "/auth/oauth2/token" }, "clientCredentials": { "scopes": { "all:read": "Read only: List and retrieve information about all resources", "all:write": "Full Access: Grant access to all scopes based on your current role permissions", "company:read": "View companies: Read and list companies", "company:write": "Manage companies: Create, Read and update companies", "company_admin": "Manage company resources: Create and manage company resources", "company_management": "Manage companies: Create and manage companies", "convert_currency:read": "Convert currencies: Convert currencies", "country:read": "View countries: Read and list countries", "employment_documents": "Manage employment documents: Manage employment documents", "employment_payments": "Manage expenses: Manage expenses and incentives", "employments": "Manage employments: Create and manage employments", "help_center_article:read": "View help articles: Read help center articles", "https://gateway.remote.com/company.manage": "Legacy scope, kept as sent. Some endpoints accept it, not all: see the endpoint's `security` in the OpenAPI file", "https://gateway.remote.com/employment.manage": "Legacy scope, kept as sent. Some endpoints accept it, not all: see the endpoint's `security` in the OpenAPI file", "invoices": "Manage invoices: Manage invoices", "payroll": "Manage payroll runs: Manage payroll runs and calendars", "payroll_calendar:read": "View payroll calendars: List payroll calendars", "pricing_plan:read": "View pricing plans: List pricing plans", "pricing_plan:write": "Manage pricing plans: Create pricing plans", "time_and_attendance": "Manage timeoffs: Manage timeoffs, leave-policies and timesheets", "webhook:read": "View webhooks: Read webhooks callback logs", "webhook:write": "Manage webhooks: Set webhook callbacks and replay webhooks" }, "tokenUrl": "/auth/oauth2/token" } }, "type": "oauth2" }, "OAuth2AuthorizationCode": { "description": "Authenticate as the token authorizer using `authorization_code` / `refresh_token` grants in the OAuth 2.0 protocol.\n", "flows": { "authorizationCode": { "authorizationUrl": "/auth/oauth2/authorize", "refreshUrl": "/auth/oauth2/token", "scopes": { "company_department:read": "View departments: Read and list company departments", "webhook:write": "Manage webhooks: Set webhook callbacks and replay webhooks", "magic_link:write": "Create magic links: Create magic links", "offboarding:write": "Manage offboarding: Creates offboarding requests", "custom_field:write": "Manage custom fields: Create custom fields", "address:write": "Manage addresses: Create and update employee residential address", "expense:read": "View expenses: List and read expenses", "employment:write": "Manage employments: Create and update employments", "identity_verification:write": "Manage identity verification: Write identity verification data", "timesheet:write": "Manage timesheets: Create timesheets", "travel_letter:write": "Manage travel letters: Create travel letters", "all:read": "Read only: List and retrieve information about all resources", "incentive:read": "View incentives: List incentives and recurring incentives", "personal_detail:read": "View personal details: Read employee personal information", "invoices:write": "Manage invoices: Create invoices", "work_authorization:write": "Manage work authorizations: Create work authorization requests", "timeoff:write": "Manage timeoffs: Create, update and cancel timeoffs", "company_structure:read": "View company structure: Show company structure", "benefit_renewal:write": "Manage benefit renewals: Update benefit renewal requests", "benefit_offer:read": "View benefit offers: List benefit offers", "employment_documents": "Manage employment documents: Manage employment documents", "onboarding:write": "Manage onboarding: Cancel onboarding", "https://gateway.remote.com/company.manage": "Legacy scope. A new request for it gets `all:write`; tokens authorized before late March 2026 may still hold it. Many endpoints accept it, but not all: see the endpoint's `security` in the OpenAPI file", "project:write": "Manage projects: Create and update company projects and their leads and team members", "pay_in_details:read": "View pay-in details: Read the payment reference and Remote's bank details for paying contractor invoices", "payroll_run:read": "View payroll runs: List and show payroll runs", "risk_reserve:write": "Manage risk reserves: Create risk reserves for a company", "invoices": "Manage invoices: Manage invoices", "resignation_letter:read": "View resignation letters: Read resignation letters", "resignation:read": "View resignations: Read resignation requests", "convert_currency:read": "Convert currencies: Convert currencies", "all:write": "Full Access: Grant access to all scopes based on your current role permissions", "https://gateway.remote.com/employment.manage": "Legacy scope. A new request for it gets `all:write`; tokens authorized before late March 2026 may still hold it. Many endpoints accept it, but not all: see the endpoint's `security` in the OpenAPI file", "employments": "Manage employments: Create and manage employments", "probation_document:read": "View probation documents: Read probation completion letters and probation extensions documents", "company_admin": "Manage company resources: Create and manage company resources", "payroll": "Manage payroll runs: Manage payroll runs and calendars", "help_center_article:read": "View help articles: Read help center articles", "timesheet:read": "View timesheets: Read timesheets", "custom_field_value:write": "Manage custom field values: Create custom field values", "company_currencies:read": "View company currencies: List company supported currencies", "payslip:read": "View payslips: List and show employee's payslip", "pay_item:write": "Manage pay items: Create pay items for employments", "resignation:write": "Manage resignations: Validate resignation requests", "custom_field:read": "View custom fields: List custom fields", "payroll_calendar:read": "View payroll calendars: List payroll calendars", "contract_amendment:write": "Manage contract amendments: Create contract amendments", "offboarding:read": "View offboarding requests: Read and list offboarding requests", "timeoff:read": "View timeoffs: Read and list timeoffs", "pay_in_details": "View pay-in bank details: Read the payment reference and Remote's receiving bank accounts for paying invoices", "probation_document:write": "Manage probation documents: Create probation completion letters and probation extensions documents", "country:read": "View countries: Read and list countries", "webhook:read": "View webhooks: Read webhooks callback logs", "company_department:write": "Manage departments: Create company departments", "company_manager:read": "View managers: Read and list company managers", "pay_item:read": "View pay items: List pay items for employments", "contract_amendment:read": "View contract amendments: List and show contract amendments", "company:read": "View companies: Read and list companies", "sso_configuration:write": "Manage SSO: Set SSO configuration", "benefit_offer:write": "Manage benefit offers: Create benefit offers", "contract_eligibility:write": "Manage contract eligibility: Create contract eligibility for an employment", "benefit_renewal:read": "View benefit renewals: List benefit renewal requests", "background_check:read": "View background checks: Read and show background check requests", "custom_field_value:read": "View custom field values: List custom field values", "expense:write": "Manage expenses: Create expenses", "identity_verification:read": "View identity verification: Read identity verification data", "address:read": "View addresses: Read employee residential address", "document:write": "Manage documents: Write and update documents", "time_and_attendance": "Manage timeoffs: Manage timeoffs, leave-policies and timesheets", "employment_payments": "Manage expenses: Manage expenses and incentives", "form:read": "View forms: Read json schema forms", "work_authorization:read": "View work authorizations: List work authorization requests", "invoices:read": "View invoices: Read and list invoices", "incentive:write": "Manage incentives: Create incentives", "employment:read": "View employments: List and read employments", "contract:read": "View contracts: List employment contracts", "projects": "Manage projects: Create and manage company projects and their leads and team members", "company_manager:write": "Manage managers: Create and delete company managers", "travel_letter:read": "View travel letters: Read travel letters", "project:read": "View projects: List and read company projects", "document:read": "View documents: Read and list documents", "sso_configuration:read": "View SSO configuration: Read SSO configuration" }, "tokenUrl": "/auth/oauth2/token" } }, "type": "oauth2" }, "OAuth2CompanyManagerAssertion": { "description": "Authenticate as a company manager using the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant in the OAuth2 protocol,\nwith an assertion whose subject is `urn:remote-api:company-manager:user:`, where `` is the\ncompany manager's Remote `user_id`. Each user belongs to one company.\n\nOpenAPI has no flow type for this grant, so it is declared as a client credentials flow. Request the token\nfrom the token URL with this grant type and a signed assertion, not with `client_credentials`.\n\nRemote must allow the integration to act on behalf of users, and the integration must manage the user's company.\nRemote can also limit an integration to grants that carry a user's consent, such as the Authorization Code flow;\nthis grant is then refused.\n\nThe token acts as that company manager, and is accepted wherever a company manager's token from the\nAuthorization Code flow is.\n", "flows": { "clientCredentials": { "scopes": { "company_department:read": "View departments: Read and list company departments", "webhook:write": "Manage webhooks: Set webhook callbacks and replay webhooks", "magic_link:write": "Create magic links: Create magic links", "offboarding:write": "Manage offboarding: Creates offboarding requests", "custom_field:write": "Manage custom fields: Create custom fields", "address:write": "Manage addresses: Create and update employee residential address", "expense:read": "View expenses: List and read expenses", "employment:write": "Manage employments: Create and update employments", "identity_verification:write": "Manage identity verification: Write identity verification data", "timesheet:write": "Manage timesheets: Create timesheets", "travel_letter:write": "Manage travel letters: Create travel letters", "all:read": "Read only: List and retrieve information about all resources", "incentive:read": "View incentives: List incentives and recurring incentives", "personal_detail:read": "View personal details: Read employee personal information", "invoices:write": "Manage invoices: Create invoices", "work_authorization:write": "Manage work authorizations: Create work authorization requests", "timeoff:write": "Manage timeoffs: Create, update and cancel timeoffs", "company_structure:read": "View company structure: Show company structure", "benefit_renewal:write": "Manage benefit renewals: Update benefit renewal requests", "benefit_offer:read": "View benefit offers: List benefit offers", "employment_documents": "Manage employment documents: Manage employment documents", "onboarding:write": "Manage onboarding: Cancel onboarding", "https://gateway.remote.com/company.manage": "Legacy scope. A request that includes it gets a token with only `all:write`, so no assertion token holds it. Request `all:write` or a narrower scope instead", "project:write": "Manage projects: Create and update company projects and their leads and team members", "pay_in_details:read": "View pay-in details: Read the payment reference and Remote's bank details for paying contractor invoices", "payroll_run:read": "View payroll runs: List and show payroll runs", "risk_reserve:write": "Manage risk reserves: Create risk reserves for a company", "invoices": "Manage invoices: Manage invoices", "resignation_letter:read": "View resignation letters: Read resignation letters", "resignation:read": "View resignations: Read resignation requests", "convert_currency:read": "Convert currencies: Convert currencies", "all:write": "Full Access: Grant access to all scopes based on your current role permissions", "https://gateway.remote.com/employment.manage": "Legacy scope. A request that includes it gets a token with only `all:write`, so no assertion token holds it. Request `all:write` or a narrower scope instead", "employments": "Manage employments: Create and manage employments", "probation_document:read": "View probation documents: Read probation completion letters and probation extensions documents", "company_admin": "Manage company resources: Create and manage company resources", "payroll": "Manage payroll runs: Manage payroll runs and calendars", "help_center_article:read": "View help articles: Read help center articles", "timesheet:read": "View timesheets: Read timesheets", "custom_field_value:write": "Manage custom field values: Create custom field values", "company_currencies:read": "View company currencies: List company supported currencies", "payslip:read": "View payslips: List and show employee's payslip", "pay_item:write": "Manage pay items: Create pay items for employments", "resignation:write": "Manage resignations: Validate resignation requests", "custom_field:read": "View custom fields: List custom fields", "payroll_calendar:read": "View payroll calendars: List payroll calendars", "contract_amendment:write": "Manage contract amendments: Create contract amendments", "offboarding:read": "View offboarding requests: Read and list offboarding requests", "timeoff:read": "View timeoffs: Read and list timeoffs", "pay_in_details": "View pay-in bank details: Read the payment reference and Remote's receiving bank accounts for paying invoices", "probation_document:write": "Manage probation documents: Create probation completion letters and probation extensions documents", "country:read": "View countries: Read and list countries", "webhook:read": "View webhooks: Read webhooks callback logs", "company_department:write": "Manage departments: Create company departments", "company_manager:read": "View managers: Read and list company managers", "pay_item:read": "View pay items: List pay items for employments", "contract_amendment:read": "View contract amendments: List and show contract amendments", "company:read": "View companies: Read and list companies", "sso_configuration:write": "Manage SSO: Set SSO configuration", "benefit_offer:write": "Manage benefit offers: Create benefit offers", "contract_eligibility:write": "Manage contract eligibility: Create contract eligibility for an employment", "benefit_renewal:read": "View benefit renewals: List benefit renewal requests", "background_check:read": "View background checks: Read and show background check requests", "custom_field_value:read": "View custom field values: List custom field values", "expense:write": "Manage expenses: Create expenses", "identity_verification:read": "View identity verification: Read identity verification data", "address:read": "View addresses: Read employee residential address", "document:write": "Manage documents: Write and update documents", "time_and_attendance": "Manage timeoffs: Manage timeoffs, leave-policies and timesheets", "employment_payments": "Manage expenses: Manage expenses and incentives", "form:read": "View forms: Read json schema forms", "work_authorization:read": "View work authorizations: List work authorization requests", "invoices:read": "View invoices: Read and list invoices", "incentive:write": "Manage incentives: Create incentives", "employment:read": "View employments: List and read employments", "contract:read": "View contracts: List employment contracts", "projects": "Manage projects: Create and manage company projects and their leads and team members", "company_manager:write": "Manage managers: Create and delete company managers", "travel_letter:read": "View travel letters: Read travel letters", "project:read": "View projects: List and read company projects", "document:read": "View documents: Read and list documents", "sso_configuration:read": "View SSO configuration: Read SSO configuration" }, "tokenUrl": "/auth/oauth2/token", "x-grantType": "urn:ietf:params:oauth:grant-type:jwt-bearer" } }, "type": "oauth2" } } }, "info": { "title": "Testing & Sandbox", "version": "2.0.0" }, "openapi": "3.1.0", "paths": { "/v1/sandbox/employments/{employment_id}": { "put": { "callbacks": {}, "deprecated": false, "description": "Updates an employment. Use this endpoint to:\n- modify employment states for testing\n- Backdate employment start dates\n\nThis endpoint will respond with a 404 outside of the Sandbox environment.\n\n`partner_external_id` cannot be updated here and is ignored if sent, like any other\nunsupported field. Set it with `PATCH /api/eor/v1/employments/{employment_id}` instead.\n\nFor updating an employment's parameters outside of testing purposes, use [this Employment update endpoint](#operation/patch_update_employment).\n\n## Authentication\n\nThis endpoint accepts any one of the following token types:\n\n- **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).\n- **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).\n- **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).", "operationId": "patch_v1_sandbox_employments_employment_id", "parameters": [ { "description": "An access token of one of the types listed in this endpoint's Authentication section, as `Bearer `.\n\nA token from the Refresh Token flow is of the same type as the token issued with that refresh token.\n", "example": "Bearer ACCESS_TOKEN", "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" } }, { "description": "Employment ID", "example": "e3ee69d7-1293-4664-92fc-02625dae5247", "in": "path", "name": "employment_id", "required": true, "schema": { "type": "string" }, "x-resource-type": "employment" }, { "description": "When true, returns `tax_servicing_countries` grouped into global/regions/subregions instead of a flat list of country names.", "in": "query", "name": "group_tax_servicing_countries", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmploymentUpdateParams" } } }, "description": "Employment params", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmploymentResponse" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntityResponse" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } }, "description": "Too many requests" } }, "security": [ { "OAuth2AuthorizationCode": [] }, { "OAuth2CompanyManagerAssertion": [] }, { "CustomerAPIToken": [] } ], "summary": "Update employment", "tags": [ "Sandbox" ] } } }, "security": [ { "OAuth2": [] } ], "servers": [ { "url": "https://gateway.remote.com/", "variables": {} }, { "url": "https://gateway.remote-sandbox.com/", "variables": {} } ] } ```