***
title: EOR Contract Amendment API
description: Update contract terms through a structured approval process using API
----------------------------------------------------------------------------------
The EOR contract amendment API lets you update contract terms through a structured approval process that follows predefined compliance rules.
An amendment is a change to one or more contract terms, referred to as data points, such as employment type, job title, scope, or salary. Instead of modifying the original contract document, the amendment is issued as a separate addendum to the employment agreement. The contract entity in the database, including its ID, remains the same. Only specific values, like salary, are updated with a new effective date.
You or Deel can initiate an amendment. The process includes multiple steps and requires approval from both you and the employee. Modification and approval rules vary based on the amended data point and country-specific regulations.
## Amendment flows
Amendments can be initiated by you or or by Deel. The steps an amendment goes through are different depending on who initiates it.
### Scenario when you requests an amendment
Follow these steps to create and process an amendment programmatically.
1. Create an amendment with the [Create amendment](https://developer.deel.com/api/eor-endpoints/eor-amendments/create-contract-amendment) endpoint.
2. Update fields as needed with the [Update amendment](https://developer.deel.com/api/eor-endpoints/eor-amendments/update-contract-amendment) endpoint.
3. Confirm the amendment with the [Confirm amendment](https://developer.deel.com/api/eor-endpoints/eor-amendments/confirm-contract-amendment) endpoint.
After you confirm the amendment:
* If the change is applied immediately, the API response includes the updated status.
* If the change requires approval, Deel reviews it and sends it to the employee for signing. The employee then reviews the amendment and signs it with the [Sign amendment (employee)](https://developer.deel.com/api/eor-endpoints/eor-amendments/sign-eor-amendment) endpoint.
### Scenario when Deel requests an amendment
Follow these steps to process an amendment requested by Deel.
Follow these steps to process an amendment requested by Deel.
1. Deel creates an amendment.
2. You review the amendment and either:
* Accept it with the [Accept amendment (client)](https://developer.deel.com/api/eor-endpoints/eor-amendments/accept-contract-amendment) endpoint.
* Cancel, it with the [Cancel amendment](https://developer.deel.com/api/eor-endpoints/eor-amendments/delete-contract-amendment).
3. If you accept the amendment, the employee reviews and signs it with the [Sign amendment (employee)](https://developer.deel.com/api/eor-endpoints/eor-amendments/sign-eor-amendment) endpoint.
### When does deel create amendments?
Deel may create amendments in the following cases:
* At your request. When you ask for a change that requires Deel involvement.
* To ensure compliance. When a contract update is needed to meet legal or regulatory requirements.
* For restricted changes. Some updates are only available through admin amendments due to system limitations or internal policies.
### Webhook events
Webhooks are triggered at key stages of the amendment process and provide automatic updates on status changes.
| Event | Description |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EOR_AMENDMENT_V2_IN_REVIEW` | Triggered when you create an amendment. Sent after the amendment is confirmed. |
| `EOR_AMENDMENT_V2_CLIENT_SIGN` | Triggered when Deel creates an amendment. Sent after a Deel admin creates the amendment. |
| `EOR_AMENDMENT_V2_EMPLOYEE_SIGN` | Triggered when you accept an amendment created by Deel. Sent after you review and accept the amendment. |
| `EOR_AMENDMENT_V2_CLIENT_ACTIVE` | Triggered when an amendment becomes active. Sent once all necessary approvals are complete. |
| `EOR_AMENDMENT_V2_CLIENT_REJECTED` | Triggered when an amendment is canceled. Sent when a Deel admin rejects the amendment. |
| `EOR_AMENDMENT_V2_CLIENT_VOID` | Triggered when an amendment is voided. Sent when the void deadline has passed for an in-progress amendment, meaning it can no longer become active. |
### Amendment types
Each amendment has a type that determines how it is processed. The type is returned in the response when creating or updating an amendment. It is based on the amendment settings and the data points being amended.
An amendment can have one of the following types:
* `INSTANT`: Activated immediately after you confirm it. No Deel review or employee signature is required.
* `AUTOMATED`: Activated once the employee signs it. Deel review is not required.
* `LEGAL` or `OPS`: Requires Deel review because at least one data point is set to require internal review. The difference between `LEGAL` and `OPS` is internal only and relates to how Deel conducts the review. For example, the review may involve document preparation. After Deel completes the review, the amendment is sent to the employee for review and signature. The amendment is activated once the employee signs it.
* `DISABLED`: Contains at least one data point that is restricted from being changed by the amendment settings.
* `CUSTOM`: Manually created by a Deel admin.
If at least one data point requires Deel review (
`LEGAL`
or
`OPS`
), the amendment type is set to match. Data points that would otherwise be
`INSTANT`
or
`AUTOMATED`
follow the same review and activation flow as
`LEGAL`
or
`OPS`
amendments.
### Examples
#### Example 1: Germany (instant amendment)
In this Germany example, both `holidays` (holiday increase) and `timeOffType` changes are instant. They are activated once the amendment becomes active.
The amendment `type` is `INSTANT`. In `items`, each data point also has `INSTANT` as its type:
```json
{
"type": "INSTANT",
"items": [
{
"data_point": "holidays",
"id": "59d9a2d5-9ea0-4f7f-8ac0-1db66e62d9fa",
"item": "holidaysIncrease",
"type": "INSTANT",
"previous_value": "6",
"new_value": "12"
},
{
"data_point": "timeOffType",
"id": "78743852-4dea-4b7c-bbac-44828a7d9b97",
"item": "timeOffType",
"type": "INSTANT",
"previous_value": "STANDARD",
"new_value": "SPECIFIC"
}
]
}
```
#### Example 2: Greece (legal amendment)
For Greece, the same data points require Deel review because one of the items has the `LEGAL` type:
```json
{
"type": "LEGAL",
"items": [
{
"data_point": "holidays",
"id": "f783003f-777f-425a-9a14-faf6457b7585",
"item": "holidaysIncrease",
"type": "INSTANT",
"previous_value": "6",
"new_value": "10"
},
{
"data_point": "timeOffType",
"id": "d9dffd0a-6443-4992-9aa7-d859bd9d4d4d",
"item": "timeOffType",
"type": "LEGAL",
"previous_value": "STANDARD",
"new_value": "SPECIFIC"
}
]
}
```
## Retrieve contract information for amendment
To retrieve available amendment settings, you first need the contract ID. Use the [List of contracts](https://developer.deel.com/api/endpoints/contracts/get-contracts) endpoint to retrieve your contracts. You can filter and sort the list to find the correct `contract_id`.
Use the returned `contract_id` in the next step.
```shell
curl --location -g --request GET '{{host}}/rest/v2/contracts?limit=2&sort_by=worker_name&order_direction=desc' \
--header 'Authorization: Bearer {{token}}'
```
## Retrieve amendment settings
Once you have a contract ID, use it to retrieve valid amendment settings using [Get Amendment validation settings](https://developer.deel.com/api/eor-endpoints/eor-amendments/get-contract-amendments-validation-settings) endpoint. These are based on the contract and country-specific rules.
Use the `contract_id` path parameter to fetch available data points and rules. This returns all configurable data points and validation logic.
```shell
curl --location -g --request GET '{{host}}/rest/v2/eor/contracts/{{contract_id}}/amendments/validation/settings' \
--header 'Authorization: Bearer {{token}}'
```
The validation settings endpoint accepts optional `employment_state` query parameter to provide more accurate validation rules based on intended state/region for the employee. Use this when you need to amend the `employment_state` and need validation rules specific to the new state. For example, hourly rate minimum wages can vary by state. If not provided, the current contract's employment state is used for validation rules.
#### Example with query parameters
```shell
curl --location -g --request GET '{{host}}/rest/v2/eor/contracts/{{contract_id}}/amendments/validation/settings?employment_state=CA' \
--header 'Authorization: Bearer {{token}}'
```
### Example response
```json
[
{
"data_point": "notice_period_type",
"rules": [
{
"nullable": false,
"is_editable": true,
"possible_options": [
"STANDARD",
"CUSTOM"
],
"requires": {
"employment_type": "FULL_TIME"
}
},
{
"nullable": false,
"is_editable": true,
"possible_options": [
"STANDARD",
"CUSTOM"
],
"requires": {
"employment_type": "PART_TIME"
}
}
]
}
]
```
## Understand how amendment settings work
The response for `amendment-settings` includes a list of configurable contract fields. Each field is described by a `data_point` object that defines how it can be changed.
Key elements:
* Each `data_point` represents an attribute in the contract that may be amended.
* The `requires` object defines conditions that must be met for the change to be allowed. All fields in `requires` must match either the current contract or the amendment request.
* Numeric fields include `min` and `max` constraints.
* `possible_options` lists the allowed values for the data point.
* `is_editable` indicates if the field can be updated. If a field is not editable, the reason is not returned in the API. It may be due to country rules, amendment restrictions, or other pending amendments, for example, currency.
* `additional_details` may include validation notes or business constraints.
* Date fields can include `min_date` and `max_date`, formatted as `YYYY-MM-DD`, for example, `2025-06-17`.
### Examples of amendment rules
These examples show how the API applies rules to control when you can update specific fields.
#### Require a field in the contract or request
You can only apply this rule if the contract or amendment request includes `contract_term: "DEFINITE"`.
```json
{
"nullable": false,
"is_editable": true,
"min_date": "2025-06-02",
"requires": {
"contract_term": "DEFINITE"
}
}
```
#### Employment type restriction
You can set `employment_type` to `FULL_TIME` only if `contract_term` is `INDEFINITE`.
```json
{
"nullable": false,
"is_editable": true,
"possible_options": ["FULL_TIME"],
"requires": { "contract_term": "INDEFINITE" }
}
```
#### Numeric constraints
This rule allows minimum and maximum values when `employment_type` is `FULL_TIME`.
```json
{
"nullable": false,
"is_editable": true,
"min": 6,
"max": 12,
"requires": { "employment_type": "FULL_TIME" }
}
```
#### Use external validation
This rule indicates that complete validation requires calling the [validate-amendment](https://developer.deel.com/api/eor-endpoints/eor-amendments/validate-eor-amendments) endpoint. When `external_validation: true`, you can either:
* Call the [validate amendment](https://developer.deel.com/api/eor-endpoints/eor-amendments/validate-eor-amendments) endpoint for server-side validation.
* Skip validation entirely and let the create/update endpoints return validation errors.
```json
{
"nullable": false,
"is_editable": true,
"external_validation": true
}
```
## Amendment effective date
The effective date is the date when the amendment becomes active. It defines when the changes take effect and when they appear in payroll, invoices, or other downstream processes.
Different amendment fields trigger different business logic. Based on what you are changing, Deel dynamically calculates a valid effective date range.
To support this flexibility, Deel exposes the [Effective Date Limitations](https://developer.deel.com/api/eor-endpoints/eor-amendments/get-contract-amendment-effective-date-limitations) API that you need to call to retrieve the valid effective date limits for a specific amendment. This ensures that:
* Your system always works with the correct date limits.
* Deel applies the correct validations automatically based on the amendment content, helping you avoid false validations or user errors.
* You can choose to show or disable the effective date field in your UI.
* You can apply validation rules or pre-fill values based on internal workflows.
Amendments on contracts that are not yet active can't have an effective date.
### Fetching effective date limits
You must fetch the effective date limitations:
* Immediately after creating or updating an amendment.
* Before setting or submitting the effective date.
* Before confirming the amendment, if any changes were made after fetching the last effective date.
The valid effective date range is based on the specific changes in the amendment. Always fetch the date limits only after all changes to the amendment are finalized.
### Status behavior by effective date
| Efective date | What happens |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Effective date in the future | The amendment gets an `upcoming` status. It won’t affect contract values immediately. |
| Effective date today or in the past | The amendment becomes `active` as soon as it’s processed and signed. |
| Effective date not provided | The amendment becomes `active` immediately after signing are completed, Deel uses the date when all parties confirm the amendment as the effective date. |
Amendments in
`upcoming`
status do not affect payroll, invoicing, or contract terms until they are activated by Deel’s internal job on the effective date.
### High-level flow
The diagram below shows how the effective date influences the amendment lifecycle, from creation to activation:
```mermaid
sequenceDiagram
participant Client
participant DeelAPI as Deel API
Client->>DeelAPI: Create Amendment (POST)
DeelAPI-->>Client: Amendment Flow Returned
Client->>DeelAPI: Fetch Effective Date Limits (GET)
DeelAPI-->>Client: Date Limits (min/max/default/hidden/disabled)
Note over Client: Show Calendar UI (optional)
Client->>DeelAPI: Update Amendment (PATCH with effective_date)
Client->>DeelAPI: Confirm Amendment
Note over DeelAPI: Cron activates amendment on effective_date
```
### UI behavior: is\_hidden and is\_disabled
When you fetch effective date limitations, the response includes flags that guide you in rendering the field in your UI.
| Field | Client-side behavior |
| ------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `is_hidden` | (Optional) Suggests that the field may be hidden from the user interface. You may decide whether to follow this behavior. |
| `is_disabled` | If true, the field should not be editable. You must use `default_effective_date`. |
If your use case involves applying an automatic default effective date, such as aligning it with the start of the payroll cycle, hiding the field might improve user experience.
### Effective date validation rules
The validation logic for effective dates ensures that all amendments respect configuration limits, providing flexibility while preventing invalid data entry.
| Scenario | Requirement |
| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `is_disabled = true` and `is_hidden = true` | Field must not be included in the request. |
| `is_disabled = true` and default date is present | Field must exactly match the default effective date. |
| `min_effective_date`, `max_effective_date`, or `default_effective_date` is present | A valid effective date must be provided and must fall within range. |
| No limits defined | Field is optional. System will automatically set it to when all parties confirm the amendment. |
Validation runs at two points:
* On create or update. Runs when you send the effective date in the request payload.
* On confirmation. The effective date is always validated when the amendment is confirmed, regardless of its draft status.
Draft amendments are validated only when you provide an effective date.
## Create a draft amendment
Create a new draft amendment by specifying the `contract_id`. You can include all, some, or none data points you plan to amend. This allows you to start with a basic amendment and add more details later.
```shell
curl --location -g --request POST '{{host}}/rest/v2/eor/contracts/{{contract_id}}/amendments' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"data": {
}
}'
```
OR
```shell
curl --location -g --request POST '{{host}}/rest/v2/eor/contracts/{{contract_id}}/amendments' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"data": {
"time_off_type": "SPECIFIC",
"holidays": 12,
"employment_type": "PART_TIME"
}
}'
```
## Update existing draft amendment
Update an existing draft amendment by including the `amendment_id` returned when the amendment was created. You can add additional data points, modify existing ones, or set the effective date. This endpoint allows you to build your amendment incrementally.
Updating an amendment replaces its full set of data points. Each update request must contain all the data points you want to keep, not just the one you’re changing.
If you only send the newly updated data point, any previously saved data points that are not included will be removed from the amendment.
```shell
curl --location -g --request PATCH '{{host}}/rest/v2/eor/contracts/{{contract_id}}/amendments/{{amendment_id}}' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"data": {
"time_off_type": "SPECIFIC",
"holidays": 12,
"employment_type": "PART_TIME",
"effective_date": "2025-08-01",
}
}'
```
## Amendment validation approaches
You have these options for validating amendment data points:
* Client-side validation: Use the validation rules from the [amendment settings endpoint](https://developer.deel.com/api/eor-endpoints/eor-amendments/get-contract-amendments-validation-settings) to validate fields before submission.
* Server-side validation: Use the [validate amendment](https://developer.deel.com/api/eor-endpoints/eor-amendments/validate-eor-amendments) endpoint to validate fields before submission.
* Hybrid approach: Use client-side validation for basic fields and server-side validation for complex fields with `external_validation: true`.
* No pre-validation: Skip validation and let the create/update endpoints return validation errors.
The amendment submission endpoint always performs validation and returns errors, so pre-validation is optional. However, for fields with `external_validation: true`, you may want to validate beforehand to provide better user experience or to perform AI-job-scope checks and job categorization.
### Hybrid approach
The hybrid approach combines both validation methods for optimal performance and user experience:
* Use client-side validation for fields with `external_validation: false` to provide immediate feedback.
* Use server-side validation for fields with `external_validation: true` to get complete validation.
### Validate amendment data points
Use the [validate amendment](https://developer.deel.com/api/eor-endpoints/eor-amendments/validate-eor-amendments) endpoint to validate amendment data points before submission.
The
`/validate`
endpoint is deprecated. Use
[validate amendment](https://developer.deel.com/api/eor-endpoints/eor-amendments/validate-eor-amendments)
for new implementations.
```shell
curl --location --request POST '{{host}}/rest/v2/eor/contracts/{{contract_id}}/amendments/validate-amendment' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"data": {
"job_title": "Senior Software Engineer",
"scope": "Lead development of web applications"
}
}'
```
#### Response format
The response includes validation results with field-specific error mapping:
```json
{
"data": {
"is_valid": true,
"validation_error": [],
"disabled_amendments": [],
"ai_job_scope_and_title_check": {
"is_valid": true,
"ai_scope_check_public_id": "9f9e086f-2195-4ced-a641-c62d5cd388fc"
},
"job_categorization": {
"is_valid": true,
"job_categorization_log_id": "366681cd-fe16-4be7-9e45-692a4bbc91c0",
"job_category": "Software Engineer",
"job_code": "214129"
}
}
}
```
#### Error response with field mapping
When validation fails, errors include a `field` parameter for easy frontend integration:
```json
{
"data": {
"is_valid": false,
"validation_error": [
{
"code": "AMENDMENT_ITEM_VALIDATION_FAILED",
"message": "Scope exceeds maximum length of 20,000 characters",
"field": "scope",
"details": {
"newValue": "Very long scope description...",
"previousValue": "Short scope"
}
}
],
"disabled_amendments": [],
"ai_job_scope_and_title_check": null,
"job_categorization": null
}
}
```
### Seniority ID
To amend `seniority_id`:
1. Retrieve the list of avaialble levels using the [Get Seniority List](https://developer.deel.com/api/reference/endpoints/lookups/retrieve-seniority-levels) endpoint.
2. Include the selected `seniority_id` in your amendment request.
### Effective date limitations
Follow these steps to use effective date limitations:
1. Create an amendment using the [Create Amendment endpoint](https://developer.deel.com/api/eor-endpoints/eor-amendments/create-contract-amendment) endpoint.
2. Call the [Get Effective Date Limitations](https://developer.deel.com/api/eor-endpoints/eor-amendments/get-contract-amendment-effective-date-limitations) endpoint.
3. Use the returned rules to set the effective date in the UI.
4. (Optional) If required, submit the amendment with an effective date.
### AI job scope check and job categorization
#### AI review check
* When a job title/scope amendment is created or updated, an AI review check is triggered to ensure the new job title/scope aligns with the existing job description and responsibilities.
* You can trigger the [validate amendment](https://developer.deel.com/api/eor-endpoints/eor-amendments/validate-eor-amendments) endpoint for the AI review check to be performed before creating/updating the job title/scope amendment.
* You can submit the amendment regardless of the AI review outcome, but if the AI review fails, the amendment will be flagged for manual review by Deel's internal team.
* You will get `ai_scope_check_public_id` when using [validate amendment](https://developer.deel.com/api/eor-endpoints/eor-amendments/validate-eor-amendments) endpoint if the AI review succeeds, which can be used to track the review status.
* You need to send this `ai_scope_check_public_id` in the amendment request so it won't require any manual review.
1. Validate job title/scope values using the [validate amendment](https://developer.deel.com/api/eor-endpoints/eor-amendments/validate-eor-amendments) endpoint:
```json
{
"url": "https://api.letsdeel.com/rest/v2/eor/contracts/{{contract_id}}/amendments/validate-amendment",
"method": "POST",
"headers": {
"accept": "application/json",
"Content-Type": "application/json",
"Authorization": "Bearer {API_TOKEN}"
},
"body": {
"data": {
"job_title": "Senior Software Manager"
}
}
}
```
Response:
```json
{
"data": {
"is_valid": true,
"validation_error": [],
"disabled_amendments": [],
"ai_job_scope_and_title_check": {
"is_valid": true,
"ai_scope_check_public_id": "9f9e086f-2195-4ced-a641-c62d5cd388fc"
},
"job_categorization": null
}
}
```
2. Create or update amendment request using `ai_scope_check_public_id`:
```json
{
"url": "https://api.letsdeel.com/rest/v2/eor/contracts/{{contract_id}}/amendments/{{amendment_id}}",
"method": "PATCH",
"headers": {
"accept": "application/json",
"Content-Type": "application/json",
"Authorization": "Bearer {API_TOKEN}"
},
"body": {
"job_title": "Senior Software Manager",
"additional_info": {
"ai_scope_check_public_id": "9f9e086f-2195-4ced-a641-c62d5cd388fc"
}
}
}
```
#### Job categorization with AI recommendations
* Job categorization is only available for specific countries. You can see the list of countries where job categorization is supported in the following table:
| Country | AI Generates |
| -------- | --------------------- |
| Bulgaria | Job code and category |
| Latvia | Job code and category |
| Romania | Job code and category |
| Ukraine | Job category |
* Every time when a job title is amended, an AI job categorization is triggered to classify the new job title into a predefined job category and code.
* You can trigger the [validate amendment](https://developer.deel.com/api/eor-endpoints/eor-amendments/validate-eor-amendments) endpoint for the AI job categorization to be performed before creating or updating the job title amendment.
* You can submit the amendment regardless of the AI job categorization outcome, but if the AI job categorization fails, the amendment will be flagged for manual review by Deel's internal team.
* You will get `job_categorization_log_id` when using [validate amendment](https://developer.deel.com/api/eor-endpoints/eor-amendments/validate-eor-amendments) endpoint if the AI job categorization succeeds, which can be used to track the review status.
* You will also get `job_code` and `job_category` along with `job_categorization_log_id` in the response if the AI job categorization succeeds.
* You need to send this `job_categorization_log_id` and `job_code` and `job_category` in create or update amendment request so it won't require any manual review.
1. Validate job title value using the [validate amendment](https://developer.deel.com/api/eor-endpoints/eor-amendments/validate-eor-amendments) endpoint:
```json
{
"url": "https://api.letsdeel.com/rest/v2/eor/contracts/{{contract_id}}/amendments/validate-amendment",
"method": "POST",
"headers": {
"accept": "application/json",
"Content-Type": "application/json",
"Authorization": "Bearer {API_TOKEN}"
},
"body": {
"data": {
"job_title": "Senior Software Manager"
}
}
}
```
Response:
```json
{
"data": {
"is_valid": true,
"validation_error": [],
"disabled_amendments": [],
"ai_job_scope_and_title_check": {
"is_valid": false,
"message": "Job scope is too short"
},
"job_categorization": {
"is_valid": true,
"job_categorization_log_id": "366681cd-fe16-4be7-9e45-692a4bbc91c0",
"job_category": "Manager, Software Development",
"job_code": "13306011"
}
}
}
```
2. Create or update the amendment using `job_categorization_log_id`:
```json
{
"url": "https://api.letsdeel.com/rest/v2/eor/contracts/{{contract_id}}/amendments/{{amendment_id}}",
"method": "PATCH",
"headers": {
"accept": "application/json",
"Content-Type": "application/json",
"Authorization": "Bearer {API_TOKEN}"
},
"body": {
"job_title": "Senior Software Manager",
"additional_info": {
"job_categorization_log_id": "366681cd-fe16-4be7-9e45-692a4bbc91c0"
},
"job_category": "Manager, Software Development",
"job_code": "13306011"
}
}
```
When you trigger the [validate amendment](https://developer.deel.com/api/eor-endpoints/eor-amendments/validate-eor-amendments) endpoint for job title amendments:
* In countries where job categorization is supported:
* Both AI check and job categorization run.
* You must send `ai_scope_check_public_id` and `job_categorization_log_id` together with `job_code` and `job_category` in the update amendment request to avoid manual review.
* In countries where job categorization is not supported:
* Only AI check runs.
#### Update amendment with both `ai_scope_check_public_id` and `job_categorization_log_id`
Use this request to update an amendment with both the AI check and job categorization identifiers:
```json
{
"url": "https://api.letsdeel.com/rest/v2/eor/contracts/{{contract_id}}/amendments/{{amendment_id}}",
"method": "PATCH",
"headers": {
"accept": "application/json",
"Content-Type": "application/json",
"Authorization": "Bearer {API_TOKEN}"
},
"body": {
"job_title": "Senior Software Manager",
"additional_info": {
"ai_scope_check_public_id": "9f9e086f-2195-4ced-a641-c62d5cd388fc",
"job_categorization_log_id": "366681cd-fe16-4be7-9e45-692a4bbc91c0"
},
"job_category": "Manager, Software Development",
"job_code": "13306011"
}
}
```
## Validation errors and disabled amendments
Amendment requests can fail if validation rules are not met. In these cases, the API returns an error response that includes details about validation errors and disabled data points.
### Standard error format
All error responses have been standardized to follow a consistent format, making them easier to interpret and integrate.
If your amendment request fails validation, the API returns an error response. The response includes details about the validation errors and disabled data points.
Each response includes a `code` and a `message` field, while the `field` attribute remains optional. This ensures that you can reliably handle errors while still receiving additional context, when available.
Mandatory fields:
| Field | Type | Description | Example |
| ------------------ | ------ | ---------------------------- | -------------------------------------- |
| `errors` | array | Array of error objects | `[{...}]` |
| `errors[].code` | string | Error code identifier | `"VALIDATION_ERROR"` |
| `errors[].message` | string | Human-readable error message | `"Internal validation error occurred"` |
Optional fields
| Field | Type | Description | Example |
| ------------------ | ------ | ------------------------------------------------------ | ------------------------------------------------ |
| `errors[].field` | string | Field name that caused the error | `"effective_date"` |
| `errors[].details` | object | Additional error context in free-form object structure | `{"previousValue": "96000", "newValue": "3000"}` |
### Common amendment error codes
| Error Code | Description | HTTP Status |
| --------------------------------------------------------------------------------------------------------------------- | ------------------------- | ----------- |
| `VALIDATION_ERROR`, `AMENDMENT_ERROR` | Request validation failed | 400 |
| `NOT_FOUND`, `CONTRACT_NOT_FOUND`, `AMENDMENT_NOT_FOUND` | Resource not found | 404 |
| `AMENDMENT_CREATION_FAILED`, `AMENDMENT_UPDATE_FAILED`, `AMENDMENT_ITEM_DISABLED`, `AMENDMENT_ITEM_VALIDATION_FAILED` | Field validation failed | 422 |
| `FORBIDDEN` | Insufficient permissions | 403 |
| `CHANGE_REQUEST_CONFIRMED`, `RESOURCE_CONFLICT` | Resource conflict | 409 |
| `INTERNAL_ERROR` | Server error | 500 |
### Error response examples
The following examples show the different types of validation and amendment errors you may encounter.
#### Request validation errors
These errors occur when the request payload fails general validation checks.
```json
{
"errors": [
{
"code": "VALIDATION_ERROR",
"message": "Internal validation error occurred"
}
]
}
```
#### General amendment errors
These errors indicate that the amendment request cannot proceed due to one or more issues.
```json
{
"errors": [
{
"message": "Amendment already in progress with ID: 5ea6c745-3f40-4fc8-864e-026ccae666e1",
"code": "AMENDMENT_ERROR"
}
]
}
```
#### Amendment field validation errors and disabled amendment
These errors appear when specific fields are invalid or disabled for the requested amendment.
```json
{
"errors": [
{
"message": "Job title is not enabled for white label API",
"code": "AMENDMENT_ITEM_DISABLED",
"field": "jobTitle"
},
{
"message": "Minimum salary for United Kingdom is $30,312.07",
"code": "AMENDMENT_ITEM_VALIDATION_FAILED",
"field": "salary",
"details": {
"previousValue": "96000.0000",
"newValue": "3000"
}
}
]
}
```
#### Amendment processing failed errors
These errors occur when an amendment cannot be updated or confirmed.
```json
{
"errors": [
{
"code": "AMENDMENT_UPDATE_FAILED",
"message": "Failed to update amendment",
"field": "amendment"
}
]
}
```
```json
{
"errors": [
{
"code": "CHANGE_REQUEST_CONFIRMED",
"message": "Change request is already confirmed",
"field": "changeRequestId"
}
]
}
```
## Amendment statuses
Amendments pass through multiple statuses from creation to completion. These statuses are returned in an array within the API response. Check the most recent status to determine the amendment's current state.
### Amendment status structure
Amendment statuses are hierarchical, meaning they can be read at multiple levels of detail. Each status has two key properties:
* NAME → Machine-readable identifier
* FRIENDLY\_NAME → Human-readable label
#### Draft stage
*Amendments that are still being prepared and can be modified.*
| NAME | FRIENDLY\_NAME | DESCRIPTION | CLIENT ACTION | NEXT STEP |
| ------- | -------------- | ----------- | ------------------------- | ---------------------------- |
| `DRAFT` | `DRAFT` | Draft | Client can edit or submit | Moves to Preparing Documents |
#### Preparing documents stage
Statuses related to document preparation and internal review. Documents are being created, reviewed, or paused for input before signatures can begin. No action required by you in this case, fetch the amendments to get the latest status.
| NAME | FRIENDLY NAME | DESCRIPTION | CLIENT ACTION | NEXT STEP |
| ----------------------------------------------------------------------- | ----------------------------- | -------------------------------------------- | ------------- | ------------------------------------------------------------- |
| `PREPARING_DOCUMENTS` | `PREPARING_DOCUMENTS` | Under review | - | Await Deel/legal review |
| `PREPARING_DOCUMENTS.AMENDMENT_REQUESTED` | `AMENDMENT_REQUESTED` | — | — | — |
| `PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.CUSTOM_REVIEW` | `CUSTOM_REVIEW` | — | — | — |
| `PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.CUSTOM_REVIEW.APPROVED_CUSTO`M | `APPROVED_CUSTOM` | — | — | — |
| `PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.CUSTOM_REVIEW.CUSTOM_REVIEW` | `CUSTOM_REVIEW` | — | — | — |
| `PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.CUSTOM_REVIEW.CUSTOM_SKIPPED` | `CUSTOM_SKIPPED` | — | — | — |
| `PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.CUSTOM_REVIEW.INIT_CUSTOM` | `INIT_CUSTOM` | — | — | — |
| `PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.EA` | `EA` | — | — | — |
| `PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.EA.DOCUMENTS_READY` | `DOCUMENTS_READY` | — | — | — |
| `PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.EA.INIT_EA` | `INIT_EA` | — | — | — |
| `PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.EA.PENDING_DOCUMENT_SUBMIT` | `AWAITING_REVIEW` | — | — | — |
| `PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.EA.READY` | `READY` | — | — | — |
| `PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.EA.SKIPPED` | `SKIPPED` | — | — | — |
| `PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.SOW` | `SOW` | — | — | — |
| `PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.SOW.DOCUMENTS_READY` | `DOCUMENTS_READY` | — | — | — |
| `PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.SOW.INIT_SOW` | `INIT_SOW` | — | — | — |
| `PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.SOW.PENDING_DOCUMENT_SUBMIT` | `AWAITING_REVIEW` | — | — | — |
| `PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.SOW.READY` | `READY` | — | — | — |
| `PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.SOW.SKIPPED` | `SKIPPED` | — | — | — |
| `PREPARING_DOCUMENTS.PAUSED` | `PAUSED` | Moved to Paused for legal inputs | — | Legal team will review it |
| `PREPARING_DOCUMENTS.PAUSED.LEGAL_REVIEW` | `AWAITING_LEGAL_INPUT` | — | — | — |
| `PREPARING_DOCUMENTS.PAUSED.LEGAL_REVIEW.DECLINED` | `DECLINED` | — | — | — |
| `PREPARING_DOCUMENTS.PAUSED.LEGAL_REVIEW.IN_PROGRESS` | `IN_PROGRESS` | — | — | — |
| `PREPARING_DOCUMENTS.PAUSED.LEGAL_REVIEW.SOLVED` | `SOLVED` | — | — | — |
| `PREPARING_DOCUMENTS.PAUSED.LEGAL_REVIEW.TO_DO` | `TO_DO` | — | — | — |
| `PREPARING_DOCUMENTS.PAUSED.LEGAL_REVIEW.WAITING_FOR_ANOTHER_TEAM` | `WAITING_FOR_ANOTHER_TEAM` | — | — | — |
| `PREPARING_DOCUMENTS.PAUSED.LEGAL_REVIEW.WAITING_FOR_CLIENT_FEEDBACK` | `WAITING_FOR_CLIENT_FEEDBACK` | — | — | — |
| `PREPARING_DOCUMENTS.PAUSED.MOBILITY_INPUT` | `AWAITING_MOBILITY_INPUT` | — | — | — |
| `PREPARING_DOCUMENTS.PAUSED.PAUSED_BY_HRX` | `PAUSED_BY_HRX` | — | — | — |
| `PREPARING_DOCUMENTS.PREPARING_DONE` | `PREPARING_DONE` | — | — | — |
| `PREPARING_DOCUMENTS.WAITING_HRX_ACTION` | `WAITING_HRX_ACTION` | Sent to HRX to process it after legal review | — | HRX will complete the amendment process and sends for signing |
| `PREPARING_DOCUMENTS.WAITING_HRX_ACTION.CUSTOM_REVIEW` | `CUSTOM_REVIEW` | — | — | — |
| `PREPARING_DOCUMENTS.WAITING_HRX_ACTION.CUSTOM_REVIEW.APPROVED_CUSTOM` | `APPROVED_CUSTOM` | — | — | — |
| `PREPARING_DOCUMENTS.WAITING_HRX_ACTION.CUSTOM_REVIEW.CUSTOM_REVIEW` | `CUSTOM_REVIEW` | — | — | — |
| `PREPARING_DOCUMENTS.WAITING_HRX_ACTION.CUSTOM_REVIEW.CUSTOM_SKIPPED` | `CUSTOM_SKIPPED` | — | — | — |
| `PREPARING_DOCUMENTS.WAITING_HRX_ACTION.CUSTOM_REVIEW.INIT_CUSTOM` | `INIT_CUSTOM` | — | — | — |
| `PREPARING_DOCUMENTS.WAITING_HRX_ACTION.EA` | `EA` | — | — | — |
| `PREPARING_DOCUMENTS.WAITING_HRX_ACTION.EA.DOCUMENTS_READY` | `DOCUMENTS_READY` | — | — | — |
| `PREPARING_DOCUMENTS.WAITING_HRX_ACTION.EA.INIT_EA` | `INIT_EA` | — | — | — |
| `PREPARING_DOCUMENTS.WAITING_HRX_ACTION.EA.PENDING_DOCUMENT_SUBMIT` | `AWAITING_REVIEW` | — | — | — |
| `PREPARING_DOCUMENTS.WAITING_HRX_ACTION.EA.READY` | `READY` | — | — | — |
| `PREPARING_DOCUMENTS.WAITING_HRX_ACTION.EA.SKIPPED` | `SKIPPED` | — | — | — |
| `PREPARING_DOCUMENTS.WAITING_HRX_ACTION.SOW` | `SOW` | — | — | — |
| `PREPARING_DOCUMENTS.WAITING_HRX_ACTION.SOW.DOCUMENTS_READY` | `DOCUMENTS_READY` | — | — | — |
| `PREPARING_DOCUMENTS.WAITING_HRX_ACTION.SOW.INIT_SOW` | `INIT_SOW` | — | — | — |
| `PREPARING_DOCUMENTS.WAITING_HRX_ACTION.SOW.PENDING_DOCUMENT_SUBMIT` | `AWAITING_REVIEW` | — | — | — |
| `PREPARING_DOCUMENTS.WAITING_HRX_ACTION.SOW.READY` | `READY` | — | — | — |
| `PREPARING_DOCUMENTS.WAITING_HRX_ACTION.SOW.SKIPPED` | `SKIPPED` | — | — | — |
#### Signature stage
These statuses indicate the amendment is awaiting or in the process of being signed. Either it awaits Deel countersign or waiting for client or employee signature.
| NAME | FRIENDLY NAME | DESCRIPTION | CLIENT ACTION | NEXT STEP |
| -------------------------------------------------- | ---------------------------- | ----------------------------- | ------------------ | ------------------------------------------- |
| `AWAITING_SIGNATURE` | `AWAITING_SIGNATURE` | Awaiting signature | - | Either Deel or Client/Employee will sign |
| `AWAITING_SIGNATURE.EA.INIT` | `INIT` | — | - | - |
| `AWAITING_SIGNATURE.EA.PENDING_COUNTERSIGN` | `PENDING_EA_COUNTERSIGN` | Waiting for Deel counter sign | - | Deel countersigns after employee has signed |
| `AWAITING_SIGNATURE.EA.PENDING_EMPLOYEE_SIGNATURE` | `PENDING_EMPLOYEE_SIGNATURE` | Waiting for employee sign | Employee must sign | - |
| `AWAITING_SIGNATURE.EA.SIGNED` | `SIGNED` | — | - | - |
| `AWAITING_SIGNATURE.EA.SKIPPED` | `SKIPPED` | — | - | - |
| `AWAITING_SIGNATURE.SOW.INIT` | `INIT` | — | - | - |
| `AWAITING_SIGNATURE.SOW.PENDING_CLIENT_SIGNATURE` | `AWAITING_CLIENT_ACCEPTANCE` | Waiting for client sign | Client must sign | - |
| `AWAITING_SIGNATURE.SOW.PENDING_COUNTERSIGN` | `PENDING_SOW_COUNTERSIGN` | Waiting for Deel counter sign | - | Deel countersigns after client has signed |
| `AWAITING_SIGNATURE.SOW.SIGNED` | `SIGNED` | — | - | - |
| `AWAITING_SIGNATURE.SOW.SKIPPED` | `SKIPPED` | — | - | - |
#### Active or upcoming stage
Statuses when an amendment is in effect or scheduled for the future.
| NAME | FRIENDLY NAME | DESCRIPTION | CLIENT ACTION | NEXT STEP |
| ---------- | ------------- | ------------------------------------------------------------------------------------------------ | ---------------- | --------- |
| `ACTIVE` | `ACTIVE` | The amendment has taken effect and its terms are now legally applied on the employee’s contract. | No action needed | - |
| `UPCOMING` | `UPCOMING` | The amendment has been approved and scheduled but is not yet effective. | - | - |
#### Cancelled, rejected, or void stage
Statuses for amendments that were canceled, rejected, or voided.
| NAME | FRIENDLY NAME | DESCRIPTION | CLIENT ACTION | NEXT STEP |
| ----------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------- | --------- |
| `CANCELLED` | `CANCELLED` | The amendment was cancelled, either by the client or internally, before completion. | - | - |
| `REJECTED` | `REJECTED` | The amendment was reviewed and explicitly rejected by Deel | - | - |
| `VOID` | `VOID` | The amendment has been voided, making it invalid. This may happen if it is superseded by another amendment or due to compliance reasons | - | - |
### How to read amendment statuses
Amendment statuses are structured in a hierarchical format, where each level provides increasing detail about the amendment’s progress.
#### 1. Parent phase
* Represents the overall stage of the amendment, for example `PREPARING_DOCUMENTS`.
* Indicates the broad area of progress, such as document preparation, review, or approval.
#### 2. Sub-step
* A more specific action within the parent phase, for example `PREPARING_DOCUMENTS.AMENDMENT_REQUESTED`.
* Helps identify what part of the larger process is currently active.
#### 3. Detailed checkpoint
* Provides the most detailed level of the amendment’s status, for example `PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.SOW.PENDING_DOCUMENT_SUBMIT`.
* Clarifies the current condition of the amendment, such as pending submission, under review, or awaiting approval.
By reading an amendment status from left to right, you can move from the broad phase to the precise checkpoint, making it easy to understand exactly where the amendment stands in the process.
### Why this matters
* Each nested level gives increasing detail about the amendment’s progress.
* The high-level phase always represents the current overall state of the amendment, for example `PREPARING_DOCUMENTS`, `ACTIVE`, `UPCOMING`, or `CANCELLED`.
* Sub-steps and detailed checkpoints record the lifecycle progression of the amendment. This is useful for auditing, troubleshooting, and tracking how the amendment evolved over time.
The parent status is the single source of truth for the amendment’s current state. The history should not be used to infer the current status, for example by taking the last status in the array.
Below is an example of an amendment status array from the API response. In this example:
* The amendment is in the `PREPARING_DOCUMENTS` phase.
* The request is logged as `PREPARING_DOCUMENTS.AMENDMENT_REQUESTED`.
* The amendment is waiting for Deel review (`PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.SOW.PENDING_DOCUMENT_SUBMIT`). Further actions are required before it can proceed.
```json
[
{
"name": "PREPARING_DOCUMENTS",
"friendly_name": "PREPARING_DOCUMENTS",
"_amendment_flow_status": {
"created_at": "2025-03-19T17:15:02.053Z"
}
},
{
"name": "PREPARING_DOCUMENTS.AMENDMENT_REQUESTED",
"friendly_name": "AMENDMENT_REQUESTED",
"_amendment_flow_status": {
"created_at": "2025-03-19T17:15:02.053Z"
}
},
{
"name": "PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.SOW.PENDING_DOCUMENT_SUBMIT",
"friendly_name": "AWAITING_REVIEW",
"_amendment_flow_status": {
"created_at": "2025-03-19T17:15:02.053Z"
}
}
]
```
## Confirm an amendment
To confirm a draft amendment, use the `contract_id` and `amendment_id`. Only draft amendment can be confirmed.
After confirmation, the flow depends on the amendment type. If the type is instant, the amendment becomes active immediately. If it requires signatures, Deel or the employee must approve it first.
```shell
curl --location -g --request PUT '{{host}}/rest/v2/eor/contracts/{{contract_id}}/amendments/{{amendment_id}}/confirm' \
--header 'Authorization: Bearer {{token}}'
```
## Cancel an amendment
To cancel an amendment, use the `contract_id` and `amendment_id`. You can cancel an amendment any time before the employee signs it. After cancellation, you can delete it if needed.
```shell
curl --location -g --request DELETE '{{host}}/rest/v2/eor/contracts/{{contract_id}}/amendments/{{amendment_id}}' \
--header 'Authorization: Bearer {{token}}'
```
## Download an amendment PDF
Retrieve the download URL for the Statement of Work (Employee Agreement, EA) of a confirmed amendment. The URL is available only after the amendment is confirmed and the contract is in progress.
The download URL expires after 15 minutes.
```shell
curl --location -g --request GET '{{host}}/rest/v2/eor/contracts/{{contract_id}}/amendments/{{amendment_id}}/pdf' \
--header 'Authorization: Bearer {{token}}'
```
## Accept an amendment
Use this endpoint to accept an amendment submitted by a Deel admin.
After acceptance, the amendment either becomes active immediately or moves to the signature step, depending on its type.
```shell
curl --location -g --request PUT '{{host}}/rest/v2/eor/contracts/{{contract_id}}/amendments/{{amendment_id}}/accept' \
--header 'Authorization: Bearer {{token}}'
```
## Sign an approved amendment
An employee can sign an amendment approved by both the client and admin. After signing, the amendment becomes active.
```shell
curl --location -g --request PUT '{{host}}/rest/v2/eor/contracts/{{contract_id}}/amendments/{{amendment_id}}/sign' \
--header 'Authorization: Bearer {{token}}'
```
## Retrieve the list of amendments
Retrieve all amendments for a specific contract.
```shell
curl --location -g --request GET '{{host}}/rest/v2/eor/contracts/{{contract_id}}/amendments' \
--header 'Authorization: Bearer {{token}}'
```
## Retrieve a specific amendment
Retrieve details of a specific amendment
```shell
curl --location -g --request GET '{{host}}/rest/v2/eor/contracts/{{contract_id}}/amendments/{{amendment_id}}' \
--header 'Authorization: Bearer {{token}}'
```
## Custom amendment items
Custom amendment items are used when you request changes that:
* Involve data points not supported or not available in the standard amendment flow.
* Modify general employment agreement wording for active contracts.
* Include other ad-hoc or unique change requests not covered by standard items.
Once the amendment is confirmed, these custom items are reviewed by internal Deel teams.
### Lifecycle and behavior
* Custom amendment items are part of an amendment, just like standard amendment items, and therefore follow the same overall amendment lifecycle:\
`created → confirmed → reviewed`
* Custom items also have a separate internal lifecycle. They have their own statuses and can be approved or rejected independently of the overall amendment.
* If an amendment includes both standard and custom items, and only the custom items are rejected, the amendment may still proceed with the standard changes.
* Exception: If the amendment contains only custom items and they are rejected, the entire amendment will be rejected.
### Custom amendment item types
If a specific data point is not available in the standard amendment flow, you can use one of the predefined custom item types to request the change. These types represent the area of the contract or employment terms you want to amend:
| Type | Description |
| ------------------------ | --------------------------------------------------------------------- |
| `START_DATE` | Request to change the employee’s contract start date. |
| `END_DATE` | Request to update the employee’s contract end date. |
| `BENEFITS` | Add or update benefits such as health insurance or allowances. |
| `PROBATION_PERIOD` | Update the probation period length or terms. |
| `VARIABLE_COMPENSATIONS` | Adjust variable pay components such as bonuses or commissions. |
| `INCENTIVE_PLAN` | Modify or add incentive plans. |
| `SALARY` | Request a change to the base salary. |
| `FIXED_ALLOWANCES` | Add or update fixed allowances, for example bonus or housing. |
| `JOB_TITLE` | Change the employee’s official job title. |
| `SENIORITY_ID` | Update job seniority level. |
| `SENIORITY_DATE` | Update the date of previous employment before the employee transfers. |
| `JOB_CODE` | Update the internal job code classification. |
| `JOB_CATEGORY` | Reclassify into a different internal job category. |
| `JOB_SCOPE` | Change the scope of responsibilities in the role. |
| `EMPLOYMENT_TYPE` | Update employment type, for example full-time or part-time. |
| `PERSONAL_DATA` | Request updates to employee personal information. |
| `OTHER` | For unique or ad-hoc requests not covered by the predefined types. |
Use the `OTHER` custom amendment type for ad-hoc or unique changes that are not covered by the predefined types.
Here is a request example for custom items with amendment:
```shell
curl --location -g --request POST '{{host}}/rest/v2/eor/contracts/{{contract_id}}/amendments' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"data": {
"time_off_type": "SPECIFIC",
"holidays": 12,
"employment_type": "PART_TIME",
"custom": [
{
"description": "Change start date to the 1st of November 2026",
"type": "START_DATE"
},
{
"description": "Add fixed allowances to the contract with these details.",
"type": "FIXED_ALLOWANCES"
},
{
"description": "Change the contract term to Part time",
"type": "OTHER"
}
]
}
}'
```
## Amendment general rules and settings
Amendments follow certain global rules and configuration options. These settings define how specific data points behave across different contract types and countries.
Probation period settings
The `probation_period` data point supports multiple rule types and constraints, depending on the contract type and country-specific settings.
Probation period values are returned with their applicable time unit in the `additional_details.time_unit` field of the validation rules response. Time units can vary by country and employment type and may be `DAY`, `WEEK`, or `MONTH`. Always check the `time_unit` field to correctly interpret the `min` and `max` values for probation period.
#### Rule-based configuration
Set the probation period based on a rule and cap value:
```json
{
"rule": "ONE_QUARTER_OF_CONTRACT_DURATION",
"cap": 100,
"time_unit": "DAY"
}
```
#### Tenure-based configuration
Other configurations define probation periods based on the employee’s expected duration of employment:
```json
{
"minEmploymentDuration": 6,
"maxEmploymentDuration": 12,
"employmentDurationType": "MONTH",
"probationPeriod": 90
}
```
#### Employment terms configuration
* For `INDEFINITE` contracts, the probation period must be between 90 and 180 days, regardless of whether the employment type is FULL\_TIME or PART\_TIME.
* For `DEFINITE` contracts, the minimum probation period is 20 days. The maximum value is calculated dynamically.
##### Dynamic calculation for definite contracts
When the contract term is `DEFINITE`, the API calculates the maximum probation period using `contract_duration_in_days` and the country-specific rule `eor_country_data.max_probation_type_for_definite`.
Available rule types:
`HALF_OF_CONTRACT_DURATION`
* Maximum probation period is half the contract duration.
Example: A 180-day contract allows up to 180 / 2 = 90 days.
`ONE_QUARTER_OF_CONTRACT_DURATION`
* Maximum probation period is one-quarter of the contract duration.
Example: A 180-day contract allows up to 180 / 4 = 45 days.
`ONE_THIRD_OF_CONTRACT_DURATION` (Default)
* If no country rule is defined, the fallback is one-third of the contract duration.
Example: A 180-day contract allows up to 180 / 3 = 60 days.
##### Cap on maximum probation period
The API may apply a cap to limit the maximum probation period, even when it uses a duration-based rule.
* If `additional_details` includes a cap value, the system uses the lower value between the calculated maximum and the cap.
* The cap applies only when the probation period is based on:
* `HALF_OF_CONTRACT_DURATION`
* `ONE_QUARTER_OF_CONTRACT_DURATION`
* `ONE_THIRD_OF_CONTRACT_DURATION`
Example:
If the contract duration is 180 days and the rule is `HALF_OF_CONTRACT_DURATION`, the calculated maximum is 90 days. However, if a cap of 60 days exists in `additional_details`, the maximum probation period is limited to 60 days.
This ensures that the probation period for DEFINITE contracts remains proportional to the contract length while complying with country-specific regulations and additional constraints.
`probation_period` settings for `DEFINITE` contracts only support the rule-based configurations listed above.
### Notice period settings
The notice period defines how far in advance either party must give notice to end the contract. Different rules apply depending on probation and contract configuration.
Notice period values are returned with their applicable time unit in the
`additional_details.time_unit`
field of the validation rules response. Time units can vary by country but are typically
`WEEK`
. Always check the
`time_unit`
field to correctly interpret the
`min`
and
`max`
values for notice period. See the example rule definition below which shows
`"time_unit": "WEEK"`
.
#### Settings for notice period after probation rules
The `notice_period_after_probation` data point follows specific rules based on `employment_type` and `notice_period_type`.
#### Notice period general rules
These rules apply only when notice\_period\_type is set to `CUSTOM`.
* The `min` and `max` notice period values range from 0 to 12 weeks.
* Rules vary for `FULL_TIME` and `PART_TIME` employees.
* The notice period *before* probation must always be shorter than the notice period *after* probation.
#### Tenure-based notice period
Only `notice_period_after_probation` supports tenure-based rules. These rules depend on the contract duration and define different notice period values for different tenure ranges.
#### Example rule definition
```json
{
"data_point": "notice_period_after_probation",
"rules": [
{
"nullable": true,
"min": 0,
"max": 12,
"is_editable": true,
"requires": {
"notice_period_type": "CUSTOM",
"employment_type": "FULL_TIME"
},
"additional_details": {
"tenure_based_rules": [
{
"maxEmploymentDuration": 24,
"minEmploymentDuration": 12,
"noticeValue": 30,
"employmentDurationType": "MONTH"
},
{
"maxEmploymentDuration": 34,
"minEmploymentDuration": 25,
"noticeValue": 50,
"employmentDurationType": "MONTH"
}
],
"time_unit": "WEEK",
"note": "Notice period before probation should be less than notice period after probation"
}
},
{
"nullable": false,
"min": 0,
"max": 12,
"is_editable": true,
"requires": {
"notice_period_type": "CUSTOM",
"employment_type": "PART_TIME"
},
"additional_details": {
"time_unit": "WEEK",
"note": "Notice period before probation should be less than notice period after probation"
}
}
]
}
```
## How to create and process amendment with examples
### 1. Retrieve amendment settings
```shell
curl --location --request GET '{{host}}/rest/v2/eor/contracts/{{contract_id}}/amendments/validation/settings' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
}'
```
Response:
```json
{
"data": [
{
"data_point": "CONTRACT_TERM",
"rules": [
{
"nullable": false,
"is_editable": true,
"possible_options": [
"DEFINITE",
"INDEFINITE"
]
}
]
},
{
"data_point": "CUSTOM",
"rules": [
{
"nullable": false,
"is_editable": true,
"possible_options": [
"START_DATE",
"END_DATE",
"BENEFITS",
"PROBATION_PERIOD",
"VARIABLE_COMPENSATIONS",
"INCENTIVE_PLAN",
"SALARY",
"FIXED_ALLOWANCES",
"JOB_TITLE",
"SENIORITY_ID",
"SENIORITY_DATE",
"JOB_CODE",
"JOB_CATEGORY",
"JOB_SCOPE",
"EMPLOYMENT_TYPE",
"PERSONAL_DATA",
"OTHER"
]
}
]
},
{
"data_point": "EMPLOYMENT_TYPE",
"rules": [
{
"nullable": false,
"is_editable": true,
"possible_options": [
"FULL_TIME"
]
}
]
}
]
}
```
### 2. Create amendment
```shell
curl --location POST '{{host}}/rest/v2/eor/contracts/374xe7e/amendments/' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data '{
"data": {
}
}'
```
Response
```json
{
"data": {
"id": "993f6533-e941-47a3-962d-f871359076ff",
"effective_date": null,
"salary": "96000.0000",
"employment_type": "FULL_TIME",
"seniority_id": 1,
"job_title": "Chief Quality Liaison",
"time_off_type": "STANDARD",
"probation_period_type_for_definite": null,
"document_type": "SOW_EA",
"holidays": 25,
"probation_period": 180,
"scope": "Chief Quality Liaison",
"employee_nationality": "PH",
"employment_state": null,
"start_date": "2025-08-05T20:15:05.872Z",
"end_date": null,
"work_hours_per_week": "40.00",
"sick_leave_days": null,
"type": "OPS",
"created_at": "2025-08-29T10:31:54.514Z",
"updated_at": "2025-08-29T10:31:54.539Z",
"requested_by": 2856213,
"is_hrx_action_needed": false,
"legal_context": null,
"rejection_context": null,
"void_deadline": null,
"void_deadline_type": null,
"notice_period_type": null,
"notice_period_after_probation": "5",
"notice_period_during_probation": "1",
"notice_period_time_unit": "WEEK",
"currency": "USD",
"is_effective_date_updated": false,
"description": null,
"work_schedule_id": null,
"work_schedule_rules_version": null,
"source": "PUBLIC_API",
"job_category": null,
"job_code": null,
"seniority_date": null,
"custom_items": [],
"amendment_statuses": [
{
"name": "DRAFT",
"friendly_name": "DRAFT",
"amendment_flow_status": {
"created_at": "2025-08-29T10:31:54.552Z"
}
}
],
"items": []
}
}
```
#### 2.1 (Optional) Update the amendment using id from the response, if needed
```shell
curl --location PATCH '{{host}}/rest/v2/eor/contracts/374xe7e/amendments/993f6533-e941-47a3-962d-f871359076ff' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data '{
"data": {
"probation_period": 20
}
}'
```
Response
```json
{
"data": {
"id": "993f6533-e941-47a3-962d-f871359076ff",
"effective_date": null,
"salary": "96000.0000",
"employment_type": "FULL_TIME",
"seniority_id": 1,
"job_title": "Chief Quality Liaison",
"time_off_type": "STANDARD",
"probation_period_type_for_definite": null,
"document_type": "SOW_EA",
"holidays": 25,
"probation_period": 20,
"scope": "Chief Quality Liaison",
"employee_nationality": "PH",
"employment_state": null,
"start_date": "2025-08-05T20:15:05.872Z",
"end_date": null,
"work_hours_per_week": "40.00",
"sick_leave_days": null,
"type": "AUTOMATED",
"created_at": "2025-08-29T10:31:54.514Z",
"updated_at": "2025-08-29T10:41:10.880Z",
"requested_by": 2856213,
"is_hrx_action_needed": false,
"legal_context": null,
"rejection_context": null,
"void_deadline": null,
"void_deadline_type": null,
"notice_period_type": null,
"notice_period_after_probation": "5",
"notice_period_during_probation": "1",
"notice_period_time_unit": "WEEK",
"currency": "USD",
"is_effective_date_updated": false,
"description": null,
"work_schedule_id": null,
"work_schedule_rules_version": null,
"source": "PUBLIC_API",
"job_category": null,
"job_code": null,
"seniority_date": null,
"custom_items": [],
"amendment_statuses": [
{
"name": "DRAFT",
"friendly_name": "DRAFT",
"amendment_flow_status": {
"created_at": "2025-08-29T10:31:54.552Z"
}
}
],
"items": [
{
"data_point": "PROBATION_PERIOD",
"id": "a643c866-66dc-4809-bc42-0d8b418bdc2b",
"item": "PROBATION_PERIOD_DECREASE",
"type": "AUTOMATED",
"previous_value": "180",
"new_value": "20"
}
]
}
}
```
#### 2.2 (Optional) Use the amendment `id` to fetch the effective date limits. If you support it, display a calendar using the date limits and flags returned in the response
```shell
curl --location GET 'https://api-gateway.deel.training/rest/v2/eor/contracts/mdyyevp/amendments/993f6533-e941-47a3-962d-f871359076ff/effective-date-limitations' \
--header 'Authorization: Bearer {API_TOKEN}'
```
Response
```shell
{
"data": {
"is_hidden": false,
"is_disabled": false,
"min_effective_date": "2025-07-01",
"max_effective_date": "2025-12-31",
"default_effective_date": "2025-08-29T00:00:00.000+00:00",
"message": "The effective date should align with the payroll cycle."
}
}
```
#### 2.3 Set the effective date by calling the [update amendment endpoint](https://developer.deel.com/api/eor-endpoints/eor-amendments/update-contract-amendment), using the `id` from the response
```shell
curl --location PATCH '{{host}}/rest/v2/eor/amendments/374xe7e/' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data
'{
"data": {
"effective_date": "2025-09-30",
"probation_period": 20
}
}'
```
Response
```json
{
"data": {
"id": "993f6533-e941-47a3-962d-f871359076ff",
"effective_date": "2025-09-30T00:00:00.000Z",
"salary": "96000.0000",
"employment_type": "FULL_TIME",
"seniority_id": 1,
"job_title": "Chief Quality Liaison",
"time_off_type": "STANDARD",
"probation_period_type_for_definite": null,
"document_type": "SOW_EA",
"holidays": 25,
"probation_period": 20,
"scope": "Chief Quality Liaison",
"employee_nationality": "PH",
"employment_state": null,
"start_date": "2025-08-05T20:15:05.872Z",
"end_date": null,
"work_hours_per_week": "40.00",
"sick_leave_days": null,
"type": "AUTOMATED",
"created_at": "2025-08-29T10:31:54.514Z",
"updated_at": "2025-08-29T10:41:10.880Z",
"requested_by": 2856213,
"is_hrx_action_needed": false,
"legal_context": null,
"rejection_context": null,
"void_deadline": null,
"void_deadline_type": null,
"notice_period_type": null,
"notice_period_after_probation": "5",
"notice_period_during_probation": "1",
"notice_period_time_unit": "WEEK",
"currency": "USD",
"is_effective_date_updated": false,
"description": null,
"work_schedule_id": null,
"work_schedule_rules_version": null,
"source": "PUBLIC_API",
"job_category": null,
"job_code": null,
"seniority_date": null,
"custom_items": [],
"amendment_statuses": [
{
"name": "DRAFT",
"friendly_name": "DRAFT",
"amendment_flow_status": {
"created_at": "2025-08-29T10:31:54.552Z"
}
}
],
"items": [
{
"data_point": "PROBATION_PERIOD",
"id": "a643c866-66dc-4809-bc42-0d8b418bdc2b",
"item": "PROBATION_PERIOD_DECREASE",
"type": "AUTOMATED",
"previous_value": "180",
"new_value": "20"
}
]
}
}
```
### 3. Confirm the amendment using the `id` from the response
```shell
curl --location --request POST '{{host}}/rest/v2/eor/contracts/mdyyevp/amendments/993f6533-e941-47a3-962d-f871359076ff/confirm' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {{token}}'
```
Response
```json
{
"data": {
"id": "993f6533-e941-47a3-962d-f871359076ff",
"effective_date": "2025-09-30T00:00:00.000Z",
"salary": "96000.0000",
"employment_type": "FULL_TIME",
"seniority_id": 1,
"job_title": "Chief Quality Liaison",
"time_off_type": "STANDARD",
"probation_period_type_for_definite": null,
"document_type": "SOW_EA",
"holidays": 25,
"probation_period": 20,
"scope": "Chief Quality Liaison",
"employee_nationality": "PH",
"employment_state": null,
"start_date": "2025-08-05T20:15:05.872Z",
"end_date": null,
"work_hours_per_week": "40.00",
"sick_leave_days": null,
"type": "AUTOMATED",
"created_at": "2025-08-29T10:31:54.514Z",
"updated_at": "2025-08-29T10:41:10.880Z",
"requested_by": 2856213,
"is_hrx_action_needed": false,
"legal_context": null,
"rejection_context": null,
"void_deadline": null,
"void_deadline_type": null,
"notice_period_type": null,
"notice_period_after_probation": "5",
"notice_period_during_probation": "1",
"notice_period_time_unit": "WEEK",
"currency": "USD",
"is_effective_date_updated": false,
"description": null,
"work_schedule_id": null,
"work_schedule_rules_version": null,
"source": "PUBLIC_API",
"job_category": null,
"job_code": null,
"seniority_date": null,
"custom_items": [],
"amendment_statuses": [
{
"name": "PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.EA",
"friendly_name": "EA",
"amendment_flow_status": {
"created_at": "2025-03-25T11:32:52.963Z"
}
},
{
"name": "PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.EA. PENDING_DOCUMENT_SUBMIT",
"friendly_name": "AWAITING_REVIEW",
"amendment_flow_status": {
"created_at": "2025-03-25T11:32:52.963Z"
}
},
{
"name": "PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.SOW",
"friendly_name": "SOW",
"amendment_flow_status": {
"created_at": "2025-03-25T11:32:52.963Z"
}
},
{
"name": "PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.SOW. PENDING_DOCUMENT_SUBMIT",
"friendly_name": "AWAITING_REVIEW",
"amendment_flow_status": {
"created_at": "2025-03-25T11:32:52.963Z"
}
},
{
"name": "PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.CUSTOM_REVIEW",
"friendly_name": "CUSTOM_REVIEW",
"amendment_flow_status": {
"created_at": "2025-03-25T11:32:52.963Z"
}
},
{
"name": "PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.CUSTOM_REVIEW. CUSTOM_SKIPPED",
"friendly_name": "CUSTOM_SKIPPED",
"amendment_flow_status": {
"created_at": "2025-03-25T11:32:52.963Z"
}
},
{
"name": "PREPARING_DOCUMENTS.AMENDMENT_REQUESTED",
"friendly_name": "AMENDMENT_REQUESTED",
"amendment_flow_status": {
"created_at": "2025-03-25T11:32:52.963Z"
}
},
{
"name": "PREPARING_DOCUMENTS",
"friendly_name": "PREPARING_DOCUMENTS",
"amendment_flow_status": {
"created_at": "2025-03-25T11:32:52.963Z"
}
}
],
"items": [
{
"data_point": "PROBATION_PERIOD",
"id": "a643c866-66dc-4809-bc42-0d8b418bdc2b",
"item": "PROBATION_PERIOD_DECREASE",
"type": "AUTOMATED",
"previous_value": "180",
"new_value": "20"
}
]
}
}
```
### 4. Wait for the amendment to be reviewed. You can monitor its status using the following endpoint
```shell
curl --location GET '{{host}}/rest/v2/eor/contracts/mdyyevp/amendments/993f6533-e941-47a3-962d-f871359076ff' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {{token}}'
```
Or you can use the webhook to get the status of the amendment
```json
{
"data": {
"meta": {
"event_type": "eor.amendment.status.updated",
"event_type_id": "de688244-7869-46db-8ac7-00083965cc9b",
"organization_id": "9c09a153-1418-4127-8c44-e99483e7c321",
"organization_name": "20TT65OV",
"tracking_id": "d09a72b0002191b65de3a453d177f1a7"
},
"resource": {
"amendment_flow_id": "116fdec2-d8b6-4c64-82d9-089cccf92731",
"organization_id": "9c09a153-1418-4127-8c44-e99483e7c321",
"status": "EOR_AMENDMENT_V2_CLIENT_ACTIVE"
}
},
"timestamp": "2025-02-07T12:36:16.360Z"
}
```
To get link to download the EA document:
```shell
curl --location GET '{{host}}/rest/v2/eor/contracts/mdyyevp/amendments/993f6533-e941-47a3-962d-f871359076ff/pdf' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {{token}}'
```
Response
```json
{
"data": {
"url": "{{host}}/eor-experience-dev/amendment_documents/fb4a3959-0a93-4dd9-9b46-7f1af60b2bbd.pdf?AWSAccessKeyId=TEST_ACCESS_KEY&Expires=1673158576&Signature=TEST_SIGNATURE"
}
}
```
If you want to cancel the amendments, you can fo it as long as it is not active. Use the following call:
```shell
curl --location --request DELETE '{{host}}/rest/v2/eor/contracts/mdyyevp/amendments/993f6533-e941-47a3-962d-f871359076ff' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {{token}}'
```
Response
```json
{
"data": {
"success": true
}
}
```
### 5. Once its review by Deel, the employee needs to sign it
```shell
curl --location --request POST '{{host}}/rest/v2/eor/contracts/mdyyevp/amendments/993f6533-e941-47a3-962d-f871359076ff/sign' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {{token}}'
```
If the amendment requires countersignature by Deel, it will be reviewed by our internal team.
Once signed, the amendment will either become `active` immediately or be scheduled to take effect on the specified effective date