Employer of RecordAmendments

Amendment Tutorial: End-to-End Walkthrough

This guide walks you through the full lifecycle of an EOR contract amendment, from retrieving validation settings to signing.

1

Retrieve amendment settings

$curl --location --request GET '{{host}}/rest/eor/contracts/{{contract_id}}/amendments/validation/settings' \
>--header 'accept: application/json' \
>--header 'Content-Type: application/json' \
>--header 'Authorization: Bearer {{token}}' \
>}'

Response:

1{
2    "data": [
3        {
4            "data_point": "CONTRACT_TERM",
5            "rules": [
6                {
7                    "nullable": false,
8                    "is_editable": true,
9                    "possible_options": [
10                        "DEFINITE",
11                        "INDEFINITE"
12                    ]
13                }
14            ]
15        },
16        {
17            "data_point": "CUSTOM",
18            "rules": [
19                {
20                    "nullable": false,
21                    "is_editable": true,
22                    "possible_options": [
23                        "START_DATE",
24                        "END_DATE",
25                        "BENEFITS",
26                        "PROBATION_PERIOD",
27                        "VARIABLE_COMPENSATIONS",
28                        "INCENTIVE_PLAN",
29                        "SALARY",
30                        "FIXED_ALLOWANCES",
31                        "JOB_TITLE",
32                        "SENIORITY_ID",
33                        "SENIORITY_DATE",
34                        "JOB_CODE",
35                        "JOB_CATEGORY",
36                        "JOB_SCOPE",
37                        "EMPLOYMENT_TYPE",
38                        "PERSONAL_DATA",
39                        "OTHER"
40                    ]
41                }
42            ]
43        },
44        {
45            "data_point": "EMPLOYMENT_TYPE",
46            "rules": [
47                {
48                    "nullable": false,
49                    "is_editable": true,
50                    "possible_options": [
51                        "FULL_TIME"
52                    ]
53                }
54            ]
55        }
56    ]
57}
2

Create amendment

$curl --location POST '{{host}}/rest/eor/contracts/{{contract_id}}/amendments/' \
>--header 'accept: application/json' \
>--header 'Content-Type: application/json' \
>--header 'Authorization: Bearer {{token}}' \
>--data '{
>    "data": {
>    }
>}'

Response:

1{
2    "data": {
3        "id": "993f6533-e941-47a3-962d-f871359076ff",
4        "effective_date": null,
5        "salary": "96000.0000",
6        "employment_type": "FULL_TIME",
7        "seniority_id": 1,
8        "job_title": "Chief Quality Liaison",
9        "time_off_type": "STANDARD",
10        "probation_period_type_for_definite": null,
11        "document_type": "SOW_EA",
12        "holidays": 25,
13        "probation_period": 180,
14        "scope": "Chief Quality Liaison",
15        "employee_nationality": "PH",
16        "employment_state": null,
17        "start_date": "2025-08-05T20:15:05.872Z",
18        "end_date": null,
19        "work_hours_per_week": "40.00",
20        "sick_leave_days": null,
21        "type": "OPS",
22        "created_at": "2025-08-29T10:31:54.514Z",
23        "updated_at": "2025-08-29T10:31:54.539Z",
24        "requested_by": 2856213,
25        "is_hrx_action_needed": false,
26        "legal_context": null,
27        "rejection_context": null,
28        "void_deadline": null,
29        "void_deadline_type": null,
30        "notice_period_type": null,
31        "notice_period_after_probation": "5",
32        "notice_period_during_probation": "1",
33        "notice_period_time_unit": "WEEK",
34        "currency": "USD",
35        "is_effective_date_updated": false,
36        "description": null,
37        "work_schedule_id": null,
38        "work_schedule_rules_version": null,
39        "source": "PUBLIC_API",
40        "job_category": null,
41        "job_code": null,
42        "seniority_date": null,
43        "custom_items": [],
44        "amendment_statuses": [
45            {
46                "name": "DRAFT",
47                "friendly_name": "DRAFT",
48                "amendment_flow_status": {
49                    "created_at": "2025-08-29T10:31:54.552Z"
50                }
51            }
52        ],
53        "items": []
54    }
55}
3

Update the amendment (optional)

Use the id from the response to update data points if needed.

$curl --location PATCH '{{host}}/rest/eor/contracts/{{contract_id}}/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:

1{
2    "data": {
3        "id": "993f6533-e941-47a3-962d-f871359076ff",
4        "effective_date": null,
5        "salary": "96000.0000",
6        "employment_type": "FULL_TIME",
7        "seniority_id": 1,
8        "job_title": "Chief Quality Liaison",
9        "time_off_type": "STANDARD",
10        "probation_period_type_for_definite": null,
11        "document_type": "SOW_EA",
12        "holidays": 25,
13        "probation_period": 20,
14        "scope": "Chief Quality Liaison",
15        "employee_nationality": "PH",
16        "employment_state": null,
17        "start_date": "2025-08-05T20:15:05.872Z",
18        "end_date": null,
19        "work_hours_per_week": "40.00",
20        "sick_leave_days": null,
21        "type": "AUTOMATED",
22        "created_at": "2025-08-29T10:31:54.514Z",
23        "updated_at": "2025-08-29T10:41:10.880Z",
24        "requested_by": 2856213,
25        "is_hrx_action_needed": false,
26        "legal_context": null,
27        "rejection_context": null,
28        "void_deadline": null,
29        "void_deadline_type": null,
30        "notice_period_type": null,
31        "notice_period_after_probation": "5",
32        "notice_period_during_probation": "1",
33        "notice_period_time_unit": "WEEK",
34        "currency": "USD",
35        "is_effective_date_updated": false,
36        "description": null,
37        "work_schedule_id": null,
38        "work_schedule_rules_version": null,
39        "source": "PUBLIC_API",
40        "job_category": null,
41        "job_code": null,
42        "seniority_date": null,
43        "custom_items": [],
44        "amendment_statuses": [
45            {
46                "name": "DRAFT",
47                "friendly_name": "DRAFT",
48                "amendment_flow_status": {
49                    "created_at": "2025-08-29T10:31:54.552Z"
50                }
51            }
52        ],
53        "items": [
54            {
55                "data_point": "PROBATION_PERIOD",
56                "id": "a643c866-66dc-4809-bc42-0d8b418bdc2b",
57                "item": "PROBATION_PERIOD_DECREASE",
58                "type": "AUTOMATED",
59                "previous_value": "180",
60                "new_value": "20"
61            }
62        ]
63    }
64}
4

Fetch effective date limits (optional)

Use the amendment id to retrieve the valid effective date range. If your UI includes a date picker, use the returned limits and flags to configure it.

$curl --location GET '{{host}}/rest/eor/contracts/{{contract_id}}/amendments/993f6533-e941-47a3-962d-f871359076ff/effective-date-limitations' \
>--header 'Authorization: Bearer {{token}}'

Response:

1{
2  "data": {
3    "is_hidden": false,
4    "is_disabled": false,
5    "min_effective_date": "2025-07-01",
6    "max_effective_date": "2025-12-31",
7    "default_effective_date": "2025-08-29T00:00:00.000+00:00",
8    "message": "The effective date should align with the payroll cycle."
9  }
10}
5

Set the effective date (optional)

Call the update amendment endpoint with the chosen effective date.

$curl --location PATCH '{{host}}/rest/eor/contracts/{{contract_id}}/amendments/993f6533-e941-47a3-962d-f871359076ff' \
>--header 'accept: application/json' \
>--header 'Content-Type: application/json' \
>--header 'Authorization: Bearer {{token}}' \
>--data '{
>    "data": {
>        "effective_date": "2025-09-30",
>        "probation_period": 20
>    }
>}'

Response:

1{
2    "data": {
3        "id": "993f6533-e941-47a3-962d-f871359076ff",
4        "effective_date": "2025-09-30T00:00:00.000Z",
5        "salary": "96000.0000",
6        "employment_type": "FULL_TIME",
7        "seniority_id": 1,
8        "job_title": "Chief Quality Liaison",
9        "time_off_type": "STANDARD",
10        "probation_period_type_for_definite": null,
11        "document_type": "SOW_EA",
12        "holidays": 25,
13        "probation_period": 20,
14        "scope": "Chief Quality Liaison",
15        "employee_nationality": "PH",
16        "employment_state": null,
17        "start_date": "2025-08-05T20:15:05.872Z",
18        "end_date": null,
19        "work_hours_per_week": "40.00",
20        "sick_leave_days": null,
21        "type": "AUTOMATED",
22        "created_at": "2025-08-29T10:31:54.514Z",
23        "updated_at": "2025-08-29T10:41:10.880Z",
24        "requested_by": 2856213,
25        "is_hrx_action_needed": false,
26        "legal_context": null,
27        "rejection_context": null,
28        "void_deadline": null,
29        "void_deadline_type": null,
30        "notice_period_type": null,
31        "notice_period_after_probation": "5",
32        "notice_period_during_probation": "1",
33        "notice_period_time_unit": "WEEK",
34        "currency": "USD",
35        "is_effective_date_updated": false,
36        "description": null,
37        "work_schedule_id": null,
38        "work_schedule_rules_version": null,
39        "source": "PUBLIC_API",
40        "job_category": null,
41        "job_code": null,
42        "seniority_date": null,
43        "custom_items": [],
44        "amendment_statuses": [
45            {
46                "name": "DRAFT",
47                "friendly_name": "DRAFT",
48                "amendment_flow_status": {
49                    "created_at": "2025-08-29T10:31:54.552Z"
50                }
51            }
52        ],
53        "items": [
54            {
55                "data_point": "PROBATION_PERIOD",
56                "id": "a643c866-66dc-4809-bc42-0d8b418bdc2b",
57                "item": "PROBATION_PERIOD_DECREASE",
58                "type": "AUTOMATED",
59                "previous_value": "180",
60                "new_value": "20"
61            }
62        ]
63    }
64}
6

Confirm the amendment

$curl --location --request POST '{{host}}/rest/eor/contracts/mdyyevp/amendments/993f6533-e941-47a3-962d-f871359076ff/confirm' \
>--header 'accept: application/json' \
>--header 'Authorization: Bearer {{token}}'

Response:

1{
2    "data": {
3        "id": "993f6533-e941-47a3-962d-f871359076ff",
4        "effective_date": "2025-09-30T00:00:00.000Z",
5        "type": "AUTOMATED",
6        "amendment_statuses": [
7            {
8              "name": "PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.EA",
9              "friendly_name": "EA",
10              "amendment_flow_status": {
11                "created_at": "2025-03-25T11:32:52.963Z"
12              }
13            },
14            {
15              "name": "PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.EA.PENDING_DOCUMENT_SUBMIT",
16              "friendly_name": "AWAITING_REVIEW",
17              "amendment_flow_status": {
18                "created_at": "2025-03-25T11:32:52.963Z"
19              }
20            },
21            {
22              "name": "PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.SOW",
23              "friendly_name": "SOW",
24              "amendment_flow_status": {
25                "created_at": "2025-03-25T11:32:52.963Z"
26              }
27            },
28            {
29              "name": "PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.SOW.PENDING_DOCUMENT_SUBMIT",
30              "friendly_name": "AWAITING_REVIEW",
31              "amendment_flow_status": {
32                "created_at": "2025-03-25T11:32:52.963Z"
33              }
34            },
35            {
36              "name": "PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.CUSTOM_REVIEW",
37              "friendly_name": "CUSTOM_REVIEW",
38              "amendment_flow_status": {
39                "created_at": "2025-03-25T11:32:52.963Z"
40              }
41            },
42            {
43              "name": "PREPARING_DOCUMENTS.AMENDMENT_REQUESTED.CUSTOM_REVIEW.CUSTOM_SKIPPED",
44              "friendly_name": "CUSTOM_SKIPPED",
45              "amendment_flow_status": {
46                "created_at": "2025-03-25T11:32:52.963Z"
47              }
48            },
49            {
50              "name": "PREPARING_DOCUMENTS.AMENDMENT_REQUESTED",
51              "friendly_name": "AMENDMENT_REQUESTED",
52              "amendment_flow_status": {
53                "created_at": "2025-03-25T11:32:52.963Z"
54              }
55            },
56            {
57              "name": "PREPARING_DOCUMENTS",
58              "friendly_name": "PREPARING_DOCUMENTS",
59              "amendment_flow_status": {
60                "created_at": "2025-03-25T11:32:52.963Z"
61              }
62            }
63        ],
64        "items": [
65            {
66                "data_point": "PROBATION_PERIOD",
67                "id": "a643c866-66dc-4809-bc42-0d8b418bdc2b",
68                "item": "PROBATION_PERIOD_DECREASE",
69                "type": "AUTOMATED",
70                "previous_value": "180",
71                "new_value": "20"
72            }
73        ]
74    }
75}
7

Wait for Deel review

Poll the amendment status endpoint or listen for the EOR_AMENDMENT_V2_CLIENT_ACTIVE webhook event.

$curl --location GET '{{host}}/rest/eor/contracts/mdyyevp/amendments/993f6533-e941-47a3-962d-f871359076ff' \
>--header 'accept: application/json' \
>--header 'Authorization: Bearer {{token}}'

Example webhook payload:

1{
2  "data": {
3    "meta": {
4      "event_type": "eor.amendment.status.updated",
5      "event_type_id": "de688244-7869-46db-8ac7-00083965cc9b",
6      "organization_id": "9c09a153-1418-4127-8c44-e99483e7c321",
7      "organization_name": "20TT65OV",
8      "tracking_id": "d09a72b0002191b65de3a453d177f1a7"
9    },
10    "resource": {
11      "amendment_flow_id": "116fdec2-d8b6-4c64-82d9-089cccf92731",
12      "organization_id": "9c09a153-1418-4127-8c44-e99483e7c321",
13      "status": "EOR_AMENDMENT_V2_CLIENT_ACTIVE"
14    }
15  },
16  "timestamp": "2025-02-07T12:36:16.360Z"
17}

To download the EA document:

$curl --location GET '{{host}}/rest/eor/contracts/mdyyevp/amendments/993f6533-e941-47a3-962d-f871359076ff/pdf' \
>--header 'accept: application/json' \
>--header 'Authorization: Bearer {{token}}'

Response:

1{
2  "data": {
3    "url": "{{host}}/eor-experience-dev/amendment_documents/fb4a3959-0a93-4dd9-9b46-7f1af60b2bbd.pdf?AWSAccessKeyId=TEST_ACCESS_KEY&Expires=1673158576&Signature=TEST_SIGNATURE"
4  }
5}

To cancel the amendment before it becomes active:

$curl --location --request DELETE '{{host}}/rest/eor/contracts/mdyyevp/amendments/993f6533-e941-47a3-962d-f871359076ff' \
>--header 'accept: application/json' \
>--header 'Authorization: Bearer {{token}}'

Response:

1{
2    "data": {
3        "success": true
4    }
5}
8

Sign the amendment (employee)

Once Deel completes its review, the employee signs the amendment.

$curl --location --request POST '{{host}}/rest/eor/contracts/mdyyevp/amendments/993f6533-e941-47a3-962d-f871359076ff/sign' \
>--header 'accept: application/json' \
>--header 'Authorization: Bearer {{token}}'

If the amendment requires a Deel countersignature, Deel’s internal team reviews it. Once signed, the amendment becomes active immediately or on the specified effective date.