Manage Employment Contracts Changes

Overview

Remote uses a versioned contract system. This means that whenever a base salary, job title, or other core terms changes, a new version of employment contract is generated. The Employment Contract API allows you to manage these versioned contract records.

Key Benefits

• Version control: Maintain a full audit trail of every contract iteration and amendment.
• Real-time sync: Use webhooks to ensure your internal system reflects the current legal source of truth.
• Compliance automation: Programmatically retrieve signed PDF artifacts for internal archiving and auditing.

ℹ️ To learn how to create an employment amendment, head over to Contract Amendments guide.

ℹ️ This guide tracks contract changes. To keep your whole copy of the workforce in sync (seed once with the list endpoint, then apply change events), see Sync your workforce data efficiently.

Initial Contract Adjustments

Before an employee's start date, the contract exists in a pre-active state. Administrative details are often refined during this periods, requiring your system to stay in sync with early adjustments.

Every time there is a modification in an employee's contract terms during onboarding, the Remote system triggers a webhook employment_contract.adjusted_during_onboarding. You can use this event to update records in your internal system to prevent stale data.

Pending Contract Changes

For onboarded employees, changes to terms (such as promotions, salary bump, etc.) begin as a proposal. These changes remain in a pending state until approved by Remote and signed by the employee.

To provide visibility within your system regarding pending changes, you can query the pending pipeline using the Get employment contract pending changes endpoint. This allows you to preview pending terms awaiting signature.

Update System for Active Contracts

After a pending contract is approved and signed off, it transitions into an active state. This is a critical change that needs to be updated in your production databases and payroll logic.

Detect the Contract Status Change

Instead of polling for status changes, your system can listen to the event triggered by the employment_contract.active_contract_updated webhook. This even confirms that the new employment terms are not legally effective.

Synchronize the New State

Once you receive the webhook update, you can fetch the full object to identify changes in the employment contract. Use the only_active=true parameter when querying the List Employment Contract. endpoint to filter out active or last active contracts. By comparing the new payload against your local database, you can trigger downstream logic, for example updating system permissions based on a new job_title.

{
  "data": {
    "employment_id": "8cf037da-317d-4ad1-8f5a-350616b3f790",
    "status": "active",
    "salary": 85000,
    "job_title": "Senior Engineer"
  }
}

You can also query this endpoint at any point in the employment lifecycle to get employment contract history of an employee. Provide the employee's employment_id and set only_active to false.

Fetch Signed Contract Documents

Every contract version is backed by a legal document. For compliance purposes, these documents are accessible through the Remote API for your internal archives.

First, call the List contract documents for an employment endpoint against a specific employment_id to retrieve a document id.

{
  "data": {
    "contract_documents": [
      {
        "id": "0073fcb5-b669-4e4a-b963-2a47744e75a1",
        "inserted_at": "2024-01-15T10:30:00Z",
        "name": "Contract Agreement.pdf",
        "status": "finished",
        "type": "contractor_services_agreement",
        "updated_at": "2024-01-16T14:20:00Z"
      }
    ],
    "current_page": 1,
    "total_count": 1,
    "total_pages": 1
  }
}

Then, use this id to call the Download file endpoint to retrieve the signed PDF into your own secure storage.