> For the complete documentation index, see [llms.txt](https://docs.samesystem.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.samesystem.dev/business-guides/employee-lifecycle-management/changes-to-employees/contract-changes.md). # Contract changes {% hint style="info" %} Only available in API v2. {% endhint %} When a user has an existing contract, this contract must NOT be updated if the following information changes: * Change of title. * Change of department. * Change of contract hours. * Change of salary (any). This is because these changes will affect schedule, calculations of payroll data and vacation, which is the reason why a new contract must be created with a new start date, from when the change becomes active. For yearly salary increases, it is recommended to create a new contract. Updating salary on an existing contract causes historical calculations to become inaccurate. Salary updates should only be used to correct data entry errors. > **Example:** > > An employee has a current contract A with an open-ended date.\ > The employee is promoted and monthly salary is changed from 2026-02-01.\ > A new contract B must be created with a start date: 2026-02-01.\ > \ > When you add a start date: 2026-02-01 for the new contract B, the end date on contract A will be automatically adjusted -1 day.

It is also possible to insert a contract into the middle of a timeline by providing and end date, ex. inserting a contract with a greater start date and an earlier end date will split an existing contract into a three-part sequence:

Insert a contract in the middle of a timeline.

### Create new contracts You will have the option below to create a new contract:

Create a new contract on existing user

A new contract can be created using a post method to this endpoint: POST /{clientToken}/users/{userId}/contracts/insert The parameter `{userId}` is the unique id number of the user in SameSystem. The value is present in the user object: `user.id`. It can also be a custom Id, like an employee id or payroll number from an external system. If a custom id is used, you must include the parameter `useCustomId=true` in the call. Request body is an object conforming to the `ContractCreateReplacingInput` schema. The following fields are required in the schema: * departmentId * startDate * titleId

Attribute:	Description:
`departmentId`	An internal (SameSystem) department id or our own external id. All departments with internal ids can be retrieved from API v1. Please see notice below.
`startDate`	This is the start date for the new contract and will be the date when the contract will be active.
`titleId`	A SameSystem title id. All titles can be retrieved from API v2.

{% hint style="info" %} If your external system uses its own identifiers, you can pass `useExternalDepartmentId=true` as a query parameter and the `departmentId` field will be treated as an external ID rather than an internal SameSystem ID. {% endhint %}

Create/update multiple users and contracts in one call (bulk creation/update)

To create and/or update multiple users with contract in a single call from a payroll or HR system with the use of a custom id (external user id), the following endpoint can be used: POST /{clientToken}/users/upsert\_with\_contracts Request body is an array of objects conforming to the `UsertUsersWithContractInput` schema. Each object in the array has a required `externalUserId` and two objects. These two objects conform with the `CreateUserWithContractUserInput` schema for the user data and the `CreateUserWithContractContractInput` for the contract data.

{% hint style="info" %} After the new contract has been created, you can see that the previous contract has been adjusted: `Previous contract end date = new contract start date – 1 day.` {% endhint %} ### Modify existing contract (corrections) If you need to correct values in a contract, you will be able to change former, active and future contracts. {% hint style="warning" %} **Notice:** You should only correct contract-defining/employment-critical data that has been created by fault (immediate corrections). Contract-defining/employment-critical data are: * Change of title. * Change of department. * Change of contract hours. * Change of salary (any). For yearly salary increases, it is recommended to create a new contract. Updating salary on an existing contract causes historical calculations to become inaccurate. Salary updates should only be used to correct data entry errors. {% endhint %} You can update any other data that is NOT contract-defining/employment-critical data, which is normally custom fields or notes. You will have the option below to modify a contract:

Modify a contract on a user

An existing contract can be modified using a put method to this endpoint: PUT /{clientToken}/contracts/{id} The parameter `{id}` is the unique id number of the contract in SameSystem. The value is present in the user object `user.contracts.id` or active contract `user.contract.id`. Request body is an object conforming to the ContractUpdateInput schema. If you receive the error message below, you have tried to update the start date on the first contract, which is not allowed: ```json { "errors":[ {"message":"Date attribute action \"write\" is not allowed","type":"validation_error","field":"date","short_message":"attribute action \"write\" is not allowed"} ]} ``` Remove startDate from the request body and update again. If you only need to update the start date on the first contract, please use this endpoint: PUT /{clientToken}/users/{id}

--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.samesystem.dev/business-guides/employee-lifecycle-management/changes-to-employees/contract-changes.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.