Time tracking | Deel | Documentation

With the time tracking API, you can manage the time worked by employees, and add, update, retrieve and delete their shifts.

The time tracking API only works for Global Payroll.

Independent contractors use timesheets to track their time. For more information, see Timesheets.

Before you begin

Before managing shifts, note the following:

Retrieve your contract ID

Shifts are linked to contracts. Retrieve the contract ID from the GET list of contracts endpoint.

Understand payroll cycles

Shifts are processed and compensated at the end of each payroll cycle. For more information, see Shifts and payroll cycles.

Late shift behavior

Shifts submitted for a past payroll cycle are compensated at the end of the current cycle without date validation.

Compensation calculation

Shifts are compensated based on the shift rate and the worker’s hourly base salary.

Shift types

Shifts can be submitted in two formats:

Categorized shifts

Shifts with known pay codes and rates defined in Deel.

Uncategorized (raw) shifts

Granular shifts capturing start time, end time, and break information.

Categorized shifts

Categorized shifts are suited for when shifts are categorized outside Deel and the shift rates (pay codes/category) are known. To use this API, you must first create shift rates in Deel and then reference those shift rates when submitting categorized shifts.

Following is an example of a categorized shift:

1 {
2   "external_id": "shift_123",
3   "date_of_work": "2024-04-01",
4   "summary": {
5     "shift_rate_external_id": "rate123",
6     "time_unit": "HOUR",
7     "time_amount": 15.50
8   }
9 }

Uncategorized (raw) shifts

Uncategorized shifts are used to capture the shift information in a more granular way. Unlike categorized shifts, which capture summary information such as total hours worked, uncategorized shifts capture granular start time, end time, and break information. There is no need to set up a shift rate for uncategorized shifts.

1 {
2   "external_id": "shift_456",
3   "date_of_work": "2024-04-01",
4   "meta": {
5     "start": {
6       "date": "2024-04-01",
7       "time": "09:00",
8       "is_rest_day": false,
9       "is_public_holiday": false
10     },
11     "end": {
12       "date": "2024-04-01",
13       "time": "17:00",
14       "is_rest_day": false,
15       "is_public_holiday": false
16     },
17     "breaks": [
18       {
19         "end": {
20           "date": "2024-04-01",
21           "time": "12:00"
22         },
23         "start": {
24           "date": "2024-04-01",
25           "time": "11:00"
26         },
27         "is_paid": true
28       }
29     ],
30     "approval_date": "2024-04-03"
31   }
32 }

Shifts and payroll cycles

When you submit a shift, the shift is automatically associated to the relevant payroll cycle based on the submission timestamp and the cycle’s cutoff date. The cutoff date is the last day for the manager to approve the submitted shifts to be processed within the current payroll cycle.

If the shift is approved before the cutoff date, the submission is processed within the current cycle
If the shift is approved after the cutoff date, the submission is processed in the next cycle

The payroll calendar is configured per entity by your Deel representative when you onboard. That is when you decide the cutoff dates. If you have questions about your cutoff dates, contact your Deel representative. For more information, see Understanding the Deel Global Payroll Calendar.

Contact support for late shift submissions

If the payroll cutoff date has already passed and waiting for the next cycle for the shift to be processed is not an option for you, you can contact support to process the shift in a special off-cycle payroll run. Off-cycle payroll runs have an additional fee that depends on your contract agreement.

Make sure to provide the shift details via a CSV file through the support channel.

Preventing late submissions with `payroll_cycle_ref.date`

To avoid accidental late submissions that result in a shift being processed in the next cycle, you can include the optional payroll_cycle_ref.date parameter when submitting a shift. This parameter ensures that the shift is only associated with the specified cycle if the submission is timely, avoiding shifts being unintentionally pushed to the next payroll cycle.

When you pass a payroll_cycle_ref.date, you’re declaring your intended payroll cycle for the shift. The system compares the request’s timestamp with the cycle’s cutoff date and checks whether the current submission falls within the specified cycle.

If the submission timestamp is before the cutoff of the current cycle, the request succeeds
If the submission timestamp is after the cutoff, the request is rejected

This validation ensures that the shift is only associated with the specified cycle if the submission is timely.

Without the payroll_cycle_ref.date parameter, the system automatically determines the cycle based on the submission time — which may lead to late shifts being silently pushed to the next cycle. Use this parameter when you want explicit alignment with a particular payroll cycle.

The following example shows how to use the payroll_cycle_ref.date parameter:

Format of the payroll_cycle_ref

The payroll_cycle_ref.date follows the ISO 8601 date and time format. You can use any date within the cycle’s start and end dates, but we recommend using the cycle’s end date for clarity.

1 {
2   "data": {
3     "contract_id": "123456",
4     "shifts": [
5       {
6         "external_id": "shift_123456",
7         "description": "This is a sample shift description.",
8         "date_of_work": "2023-10-01",
9         "payroll_cycle_ref": {
10           "date": "2023-10-31T00:00:00.000Z"
11         },
12         "summary": {
13           "shift_rate_external_id": "rate1234",
14           "time_unit": "HOUR",
15           "time_amount": 15.50
16         }
17       }
18     ]
19   }
20 }

Manage shifts

This section covers how to add, update, and delete shifts for an employee.

Add shifts

This section covers how to add shifts for an employee. There are different endpoints available for adding shifts based on the shift type:

Add categorized shifts

Add shifts with known pay codes and rates.

Add categorized shifts - Legacy

Legacy method (not recommended).

Add uncategorized (raw) shifts

Add granular shifts with detailed time information.

Add categorized shifts

You can add multiple categorized shifts for a single contract by providing an array of shifts. You can add a shift using any of the following time units: HOUR , DAY , WEEK , and MONTH.

Create a shift rate

Before submitting a categorized shift, create a shift rate and note its external_id.

Submit the shift

Make a POST request to the Create a time tracking shift endpoint.

1 import requests
2 import os
3 
4 url = "https://api.letsdeel.com/rest/v2/time_tracking/shifts"
5 
6 headers = {
7     "Authorization": f"Bearer {os.getenv('DEEL_API_TOKEN')}",
8     "Content-Type": "application/json"
9 }
10 
11 payload = {
12     "data": {
13         "contract_id": "123456",
14         "shifts": [
15             {
16                 "external_id": "shift_123456",
17                 "description": "This is a sample shift description.",
18                 "date_of_work": "2023-10-01",
19                 "payroll_cycle_ref": {
20                     "date": "2023-10-31T00:00:00.000Z"
21                 },
22                 "summary": {
23                     "shift_rate_external_id": "rate1234",
24                     "time_unit": "HOUR",
25                     "time_amount": 15.50
26                 }
27             }
28         ]
29     }
30 }
31 
32 response = requests.post(url, json=payload, headers=headers)
33 print(response.json())

In the body:

Name	Required	Type	Format	Description	Example
contract_id	true	string	-	Unique identifier of the contract for which shifts are being submitted	`123456`
description	true	string	-	Description of shift. Use it to describe what kind of work is done during the shift.	`This is a sample shift description.`
external_id	true	string	-	User-defined ID of the shift	`shift_123456`
date_of_work	true	string	date	Date on which shift is performed. It is used to identify the payroll cycle of the shift	`2023-10-01`
payroll_cycle_ref.date	false	string	date-time (ISO 8601)	Reference date of the payroll cycle in which shift should be processed (We recommend to send the payroll cycle end date as the payroll cycle reference)	`2023-10-31T00:00:00.000Z`
summary	true	object	-	Object containing numerical data about the shift. This data is used to calculate the amount to be paid for the shift.	-
summary.shift_rate_external_id	true	string	-	ID of the shift rate. Use it to link the shift to a shift rate you created.	`rate1234`
summary.time_unit	true	string	-	Time unit for the shift. Possible values: `HOUR`, `DAY`, `WEEK`, `MONTH`.	`HOUR`
summary.time_amount	false	number	-	Length of the shift, expressed in the selected time unit	`15.50`

Verify the response

A successful response (200) returns the details of the shift created.

1 {
2   "data": [
3     {
4       "external_id": "95c35493-41aa-44f8-9154-5a25cbbc1865",
5       "organization_id": 0,
6       "description": "string",
7       "date_of_work": "2019-08-24T14:15:22Z",
8       "contract_id": "string",
9       "payroll_cycle_ref": {
10         "date": "2023-10-31T00:00:00.000Z"
11       },
12       "summary": {
13         "shift_rate_external_id": "rate1234",
14         "time_unit": "HOUR",
15         "time_amount": 15.50,
16         "total_payable_hours": 15.50
17       },
18       "created_at": "2022-05-24T09:38:46.235Z",
19       "updated_at": "2022-05-24T09:38:46.235Z"
20     }
21   ]
22 }

Where:

Name	Required	Type	Format	Description	Example
external_id	true	string	-	User-defined ID of the shift	`shift_123456`
organization_id	true	number	-	The ID of your organization	`123456`
description	true	string	-	Description of shift	`This is a sample shift description.`
date_of_work	true	string	date-time	Date of the shift	`2019-08-24T14:15:22Z`
payroll_cycle_ref.date	false	string	date-time (ISO 8601)	Reference date of the payroll cycle in which shift will be processed	`2023-10-31T00:00:00.000Z`
contract_id	true	string	-	Unique identifier of the contract that shifts were submitted for	`123456`
summary	true	object	-	Object containing numerical data about the shift. This data is used to calculate the amount to be paid for the shift.	-
created_at	true	string	date-time	Date on which the shift is created	`2022-05-24T09:38:46.235Z`
updated_at	true	string	date-time	Date on which the shift is updated	`2022-05-24T09:38:46.235Z`

The total_payable_hours is set by default by the API when time_unit is HOUR.

Add categorized shifts (Legacy)

This method is still supported, but it is recommended to use Add categorized shifts instead.

This shift type adds a shift without requiring time_amount and time_unit in the request body. By default, time_amount is set to summary.total_payable_hours and time_unit is set to HOUR. You can perform the same operations on these shifts as you would with categorized shifts by using the same payload.

Create a shift rate

Before submitting a categorized shift, create a shift rate and note its external_id.

Submit the shift

Make a POST request to the Create a time tracking shift endpoint.

1 import requests
2 import os
3 
4 url = "https://api.letsdeel.com/rest/v2/time_tracking/shifts"
5 
6 headers = {
7     "Authorization": f"Bearer {os.getenv('DEEL_API_TOKEN')}",
8     "Content-Type": "application/json"
9 }
10 
11 payload = {
12     "data": {
13         "contract_id": "123456",
14         "shifts": [
15             {
16                 "external_id": "shift_123456",
17                 "description": "This is a sample shift description.",
18                 "date_of_work": "2023-10-01",
19                 "payroll_cycle_ref": {
20                     "date": "2023-10-31T00:00:00.000Z"
21                 },
22                 "summary": {
23                     "shift_rate_external_id": "rate1234",
24                     "shift_duration_hours": 8,
25                     "total_break_hours": 1,
26                     "payable_break_hours": 0.5,
27                     "total_payable_hours": 7.5
28                 }
29             }
30         ]
31     }
32 }
33 
34 response = requests.post(url, json=payload, headers=headers)
35 print(response.json())

In the body:

Name	Required	Type	Format	Description	Example
contract_id	true	string	-	Unique identifier of the contract for which shifts are being submitted	`123456`
description	true	string	-	Description of shift. Use it to describe what kind of work is done during the shift.	`This is a sample shift description.`
external_id	true	string	-	User-defined ID of the shift	`shift_123456`
date_of_work	true	string	date	Date on which shift is performed. It is used to identify the payroll cycle of the shift	`2023-10-01`
payroll_cycle_ref.date	false	string	date-time (ISO 8601)	Reference date of the payroll cycle in which shift should be processed (We recommend to send the payroll cycle end date as the payroll cycle reference)	`2023-10-31T00:00:00.000Z`
summary	true	object	-	Object containing numerical data about the shift. This data is used to calculate the amount to be paid for the shift.	-
summary.shift_rate_external_id	true	string	-	ID of the shift rate. Use it to link the shift to a shift rate you created.	`rate1234`
summary.shift_duration_hours	false	number	-	Total time of the shift in hours	`8`
summary.total_break_hours	false	number	-	Total break time in hours	`1`
summary.payable_break_hours	false	number	-	Total breaks hours that must be paid	`0.5`
summary.total_payable_hours	true	number	-	Total hours that need to be paid using the shift rate provided above	`7.5`

Verify the response

A successful response (200) returns the details of the shift created.

1 {
2   "data": [
3     {
4       "external_id": "95c35493-41aa-44f8-9154-5a25cbbc1865",
5       "organization_id": 0,
6       "description": "string",
7       "date_of_work": "2019-08-24T14:15:22Z",
8       "contract_id": "string",
9       "payroll_cycle_ref": {
10         "date": "2023-10-31T00:00:00.000Z"
11       },
12       "summary": {
13         "shift_rate_external_id": "rate1234",
14         "time_unit": "HOUR",
15         "time_amount": 7.5,
16         "shift_duration_hours": 8,
17         "total_break_hours": 1,
18         "payable_break_hours": 0.5,
19         "total_payable_hours": 7.5
20       },
21       "created_at": "2022-05-24T09:38:46.235Z",
22       "updated_at": "2022-05-24T09:38:46.235Z"
23     }
24   ]
25 }

Where:

Name	Required	Type	Format	Description	Example
external_id	true	string	-	User-defined ID of the shift	`shift_123456`
organization_id	true	number	-	The ID of your organization	`123456`
description	true	string	-	Description of shift	`This is a sample shift description.`
date_of_work	true	string	date-time	Date of the shift	`2019-08-24T14:15:22Z`
payroll_cycle_ref.date	false	string	date-time (ISO 8601)	Reference date of the payroll cycle in which shift will be processed	`2023-10-31T00:00:00.000Z`
contract_id	true	string	-	Unique identifier of the contract that shifts were submitted for	`123456`
summary	true	object	-	Object containing numerical data about the shift. This data is used to calculate the amount to be paid for the shift.	-
created_at	true	string	date-time	Date on which the shift is created	`2022-05-24T09:38:46.235Z`
updated_at	true	string	date-time	Date on which the shift is updated	`2022-05-24T09:38:46.235Z`

Add uncategorized (raw) shifts

You can add multiple uncategorized shifts for a single contract by providing an array of shifts.

Submit the shift

Make a POST request to the Create uncategorized (raw) shift endpoint.

1 import requests
2 import os
3 
4 url = "https://api.letsdeel.com/rest/v2/time_tracking/shifts/raw"
5 
6 headers = {
7     "Authorization": f"Bearer {os.getenv('DEEL_API_TOKEN')}",
8     "Content-Type": "application/json"
9 }
10 
11 payload = {
12     "data": {
13         "contract_id": "123456",
14         "shifts": [
15             {
16                 "external_id": "shift_123456",
17                 "description": "This is a sample shift description.",
18                 "date_of_work": "2024-04-01",
19                 "meta": {
20                     "start": {
21                         "date": "2024-04-01",
22                         "time": "09:00",
23                         "is_rest_day": False,
24                         "is_public_holiday": False
25                     },
26                     "end": {
27                         "date": "2024-04-01",
28                         "time": "17:00",
29                         "is_rest_day": False,
30                         "is_public_holiday": False
31                     },
32                     "breaks": [
33                         {
34                             "end": {
35                                 "date": "2024-04-01",
36                                 "time": "12:00"
37                             },
38                             "start": {
39                                 "date": "2024-04-01",
40                                 "time": "11:00"
41                             },
42                             "is_paid": True
43                         }
44                     ],
45                     "approval_date": "2024-04-03"
46                 }
47             }
48         ]
49     }
50 }
51 
52 response = requests.post(url, json=payload, headers=headers)
53 print(response.json())

In the body:

Name	Required	Type	Format	Description	Example
contract_id	true	string	-	Unique identifier of the contract for which shifts are being submitted	`123456`
external_id	true	string	-	User-defined ID of the shift	`shift_123456`
description	true	string	-	Description of shift. Use it to describe what kind of work is done during the shift.	`This is a sample shift description.`
date_of_work	true	string	date	Date on which shift is performed. It is used to identify the payroll cycle of the shift	`2024-04-01`
meta	true	object	-	Object containing detailed start/end times, breaks, and approval metadata	-
meta.start.date	true	string	date	Date when the shift starts	`2024-04-01`
meta.start.time	true	string	time (HH:mm)	Start time of the shift	`09:00`
meta.start.is_rest_day	true	boolean	-	Indicates if the shift start is on a rest day	`false`
meta.start.is_public_holiday	true	boolean	-	Indicates if the shift start is on a public holiday	`false`
meta.end.date	true	string	date	Date when the shift ends	`2024-04-01`
meta.end.time	true	string	time (HH:mm)	End time of the shift	`17:00`
meta.end.is_rest_day	true	boolean	-	Indicates if the shift end is on a rest day	`false`
meta.end.is_public_holiday	true	boolean	-	Indicates if the shift end is on a public holiday	`false`
meta.breaks	false	array	-	List of breaks taken during the shift	-
meta.breaks[].start.date	true	string	date	Break start date	`2024-04-01`
meta.breaks[].start.time	true	string	time (HH:mm)	Break start time	`11:00`
meta.breaks[].end.date	true	string	date	Break end date	`2024-04-01`
meta.breaks[].end.time	true	string	time (HH:mm)	Break end time	`12:00`
meta.breaks[].is_paid	false	boolean	-	Indicates whether the break is paid	`true`
meta.approval_date	false	string	date	Date when the shift was approved by a manager	`2024-04-03`

Verify the response

A successful response (200) returns the details of the shift created.

1 {
2   "data": [
3     {
4       "external_id": "shift_example05",
5       "description": "This is a sample shift description 5",
6       "date_of_work": "2025-06-01",
7       "created_at": "2025-06-30T19:31:54.402Z",
8       "updated_at": "2025-06-30T19:31:54.402Z",
9       "contract_id": "mjgd99e",
10       "meta": {
11         "start": {
12           "date": "2024-02-12",
13           "time": "08:00",
14           "is_rest_day": false,
15           "is_public_holiday": false
16         },
17         "end": {
18           "date": "2024-02-12",
19           "time": "16:00",
20           "is_rest_day": false,
21           "is_public_holiday": false
22         },
23         "approval_date": "2024-12-11"
24       }
25     }
26   ]
27 }

Where:

Name	Required	Type	Format	Description	Example
external_id	true	string	-	User-defined ID of the shift	`shift_example05`
description	true	string	-	Description of shift	`This is a sample shift description 5`
date_of_work	true	string	date	Date of the shift	`2025-06-01`
contract_id	true	string	-	Unique identifier of the contract that shifts were submitted for	`mjgd99e`
created_at	true	string	date-time	Date on which the shift is created	`2025-06-30T19:31:54.402Z`
updated_at	true	string	date-time	Date on which the shift is updated	`2025-06-30T19:31:54.402Z`
meta	true	object	-	Object containing detailed start/end times and approval date	-
meta.start.date	true	string	date	Date when the shift starts	`2024-02-12`
meta.start.time	true	string	time (HH:mm)	Start time of the shift	`08:00`
meta.start.is_rest_day	true	boolean	-	Indicates if the shift start is on a rest day	`false`
meta.start.is_public_holiday	true	boolean	-	Indicates if the shift start is on a public holiday	`false`
meta.end.date	true	string	date	Date when the shift ends	`2024-02-12`
meta.end.time	true	string	time (HH:mm)	End time of the shift	`16:00`
meta.end.is_rest_day	true	boolean	-	Indicates if the shift end is on a rest day	`false`
meta.end.is_public_holiday	true	boolean	-	Indicates if the shift end is on a public holiday	`false`
meta.approval_date	false	string	date	Date when the shift was approved by a manager	`2024-12-11`

List shifts in your organization

You can list the shifts in your organization and sort them by the time of creation.

Make the request

Make a GET request to the List time tracking shifts endpoint.

1 import requests
2 import os
3 
4 url = "https://api.letsdeel.com/rest/v2/time_tracking/shifts"
5 
6 headers = {
7     "Authorization": f"Bearer {os.getenv('DEEL_API_TOKEN')}"
8 }
9 
10 params = {
11     "limit": 10,
12     "offset": 20,
13     "contract_id[]": ["abcd", "abcd2"],
14     "from_date": "2023-10-01",
15     "to_date": "2023-10-02"
16 }
17 
18 response = requests.get(url, headers=headers, params=params)
19 print(response.json())

In the query:

Name	Required	Type	Format	Description	Example
limit	false	number		Number of rows that must be returned in one API call	100
offset	false	number		Number of rows that must be skipped when returning the results	10
contract_id[]	false	string[]	array param	Filter shifts by one or more contract IDs	contract_id[]=abcd&contract_id[]=efgh
from_date	false	string	YYYY-MM-DD	Filter shifts from this date (inclusive)	2023-10-01
to_date	false	string	YYYY-MM-DD	Filter shifts until this date (inclusive)	2023-10-02

Use the array syntax contract_id[]=value to filter for contract IDs. For multiple contract IDs, you can use contract_id[]=value1&contract_id[]=value2.

Review the response

A successful response (200) returns the list of shifts available in your organization and matching any filters applied.

1 {
2   "data": [
3     {
4       "external_id": "d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0",
5       "organization_id": 0,
6       "description": "string",
7       "date_of_work": "2019-08-24T14:15:22Z",
8       "contract_id": "string",
9       "summary": {
10         "shift_rate_external_id": "rate1234",
11         "time_unit": "HOUR",
12         "time_amount": 15.50,
13         "total_payable_hours": 15.50
14       },
15       "created_at": "2022-05-24T09:38:46.235Z",
16       "updated_at": "2022-05-24T09:38:46.235Z"
17     }
18   ],
19   "page": {
20     "total_rows": 0,
21     "items_per_page": 1,
22     "offset": 999999999
23   }
24 }

Where:

Name	Required	Type	Format	Description	Example
data	true	array	-	The list of shifts available	-
page	true	object	-	Contains information to navigate to the next set of results, if applicable	-

Retrieve a single shift

You can retrieve the information of a single shift using the external_id of the shift.

Make the request

Make a GET request to the Retrieve a single time tracking shift endpoint.

1 import requests
2 import os
3 
4 external_id = "shift_123456"
5 url = f"https://api.letsdeel.com/rest/v2/time_tracking/shifts/{external_id}"
6 
7 headers = {
8     "Authorization": f"Bearer {os.getenv('DEEL_API_TOKEN')}"
9 }
10 
11 response = requests.get(url, headers=headers)
12 print(response.json())

Review the response

A successful response (200) returns the information of the requested shift.

1 {
2   "external_id": "d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0",
3   "organization_id": 0,
4   "description": "string",
5   "date_of_work": "2019-08-24T14:15:22Z",
6   "contract_id": "string",
7   "summary": {
8     "shift_rate_external_id": "rate1234",
9     "time_unit": "HOUR",
10     "time_amount": 15.50,
11     "total_payable_hours": 15.50
12   },
13   "created_at": "2022-05-24T09:38:46.235Z",
14   "updated_at": "2022-05-24T09:38:46.235Z"
15 }

Update shifts

You can update a shift before it is processed for payroll. After a shift is processed, your ability to amend it depends on the shift type:

You can amend a categorized shift using correction shifts
You cannot amend uncategorized (raw) shifts

This section explains how to update shifts that have not been processed for payroll:

Update categorized shift for an employee

You can update the information of a categorized shift.

You can only update shifts that have not been processed for payroll. Shifts are processed for payroll at the cutoff date.

Make the request

Make a PATCH request to the Update a time tracking shift endpoint.

1 import requests
2 import os
3 
4 external_id = "shift_123456"
5 url = f"https://api.letsdeel.com/rest/v2/time_tracking/shifts/{external_id}"
6 
7 headers = {
8     "Authorization": f"Bearer {os.getenv('DEEL_API_TOKEN')}",
9     "Content-Type": "application/json"
10 }
11 
12 payload = {
13     "data": {
14         "description": "This is a sample shift description.",
15         "date_of_work": "2023-10-01",
16         "payroll_cycle_ref": {
17             "date": "2023-10-31T00:00:00.000Z"
18         },
19         "summary": {
20             "time_amount": 15.50
21         }
22     }
23 }
24 
25 response = requests.patch(url, json=payload, headers=headers)
26 print(response.json())

In the path:

Name	Required	Type	Format	Description	Example
external_id	true	string	-	User-defined ID of the shift	`shift_123456`

In the body:

Name	Required	Type	Format	Description	Example
data	true	object	-	Contains the information of the shift that must be updated.	-

Review the response

A successful response (200) returns the updated shift.

1 {
2   "external_id": "95c35493-41aa-44f8-9154-5a25cbbc1865",
3   "organization_id": 0,
4   "description": "string",
5   "date_of_work": "2019-08-24T14:15:22Z",
6   "contract_id": "string",
7   "payroll_cycle_ref": {
8     "date": "2023-10-31T00:00:00.000Z"
9   },
10   "summary": {
11     "shift_rate_external_id": "rate1234",
12     "time_unit": "HOUR",
13     "time_amount": 15.50,
14     "total_payable_hours": 15.50
15   },
16   "created_at": "2022-05-24T09:38:46.235Z",
17   "updated_at": "2022-05-24T09:38:46.235Z"
18 }

Update uncategorized (raw) shift for an employee

You can update the information of an uncategorized shift.

You can only update shifts that have not been processed for payroll. Shifts are processed for payroll at the cutoff date.

Make the request

Make a PATCH request to the Update a raw time tracking shift endpoint.

1 import requests
2 import os
3 
4 external_id = "shift_123456"
5 url = f"https://api.letsdeel.com/rest/v2/time_tracking/shifts/raw/{external_id}"
6 
7 headers = {
8     "Authorization": f"Bearer {os.getenv('DEEL_API_TOKEN')}",
9     "Content-Type": "application/json"
10 }
11 
12 payload = {
13     "data": {
14         "description": "This is a sample shift updated now again.",
15         "date_of_work": "2023-10-01",
16         "meta": {
17             "start": {
18                 "date": "2024-02-12",
19                 "time": "08:00",
20                 "is_rest_day": False,
21                 "is_public_holiday": False
22             },
23             "end": {
24                 "date": "2024-02-12",
25                 "time": "16:00",
26                 "is_rest_day": False,
27                 "is_public_holiday": False
28             },
29             "approval_date": "2024-12-11"
30         }
31     }
32 }
33 
34 response = requests.patch(url, json=payload, headers=headers)
35 print(response.json())

In the path:

Name	Required	Type	Format	Description	Example
external_id	true	string	-	User-defined ID of the shift	`shift_123456`

In the body:

Name	Required	Type	Format	Description	Example
data	true	object	-	Contains the information of the shift that must be updated.	-

Review the response

A successful response (200) returns the updated shift.

1 {
2   "external_id": "95c35493-41aa-44f8-9154-5a25cbbc1865",
3   "description": "string",
4   "date_of_work": "2019-08-24T14:15:22Z",
5   "contract_id": "string",
6   "payroll_cycle_ref": {
7     "date": "2023-10-31T00:00:00.000Z"
8   },
9   "meta": {
10     "start": {
11       "date": "2024-02-12",
12       "time": "08:00",
13       "is_rest_day": false,
14       "is_public_holiday": false
15     },
16     "end": {
17       "date": "2024-02-12",
18       "time": "16:00",
19       "is_rest_day": false,
20       "is_public_holiday": false
21     },
22     "approval_date": "2024-12-11"
23   },
24   "created_at": "2022-05-24T09:38:46.235Z",
25   "updated_at": "2022-05-24T09:38:46.235Z"
26 }

Delete shift for a contract

You can delete a shift for a contract by using the external_id of the shift.

You can only delete shifts that have not been processed for payroll. Shifts are processed for payroll at the cutoff date.

Make the request

Make a DELETE request to the Delete a time tracking shift endpoint.

1 import requests
2 import os
3 
4 external_id = "shift_123456"
5 url = f"https://api.letsdeel.com/rest/v2/time_tracking/shifts/{external_id}"
6 
7 headers = {
8     "Authorization": f"Bearer {os.getenv('DEEL_API_TOKEN')}"
9 }
10 
11 response = requests.delete(url, headers=headers)
12 print(response.status_code)

Where:

Name	Required	Type	Format	Description	Example
external_id	true	string	-	User-defined ID of the shift	`shift_123456`

Verify the response

A successful response (204) returns an empty body.

Correction shifts

When you need to adjust hours for shifts that have already been processed for payroll, you can use correction shifts. Corrections create a new shift entry that adjusts the payable hours of the original shift. The correction will be processed in the next payroll cycle, ensuring accurate compensation without modifying historical payroll data.

Before using correction shifts, keep in mind the following aspects:

Correction shifts can only be submitted for categorized shifts, not for uncategorized shifts.
Corrections can only be submitted for shifts that have already been processed. Unprocessed shifts can be corrected with an update.
Correction shifts cannot be submitted for another correction shift
Correction shifts cannot be updated but can be deleted

To submit a correction, use the same Create a time tracking shift endpoint, by specifying CORRECTION_DELTA as the shift_type and including a corrections array with additional fields to specify the correction details.

Identify the shift to correct

For example, you may have previously created a shift with 10 total payable hours and this shift has been already processed for payroll. If you later discover that the actual hours worked were 7.5, which requires a reduction of 2.5 hours, note the original shift’s external_id.

Submit the correction

Make a POST request to the Create a time tracking shift endpoint with the correction details.

1 import requests
2 import os
3 
4 url = "https://api.letsdeel.com/rest/v2/time_tracking/shifts"
5 
6 headers = {
7     "Authorization": f"Bearer {os.getenv('DEEL_API_TOKEN')}",
8     "Content-Type": "application/json"
9 }
10 
11 payload = {
12     "data": {
13         "contract_id": "3j5z2e6",
14         "shifts": [
15             {
16                 "external_id": "shift_example47",
17                 "description": "Correction shift",
18                 "shift_type": "CORRECTION_DELTA",
19                 "shift_reference_id": "shift_example45",
20                 "corrections": [
21                     {
22                         "type": "SUBTRACTION",
23                         "time_amount": 2.5
24                     }
25                 ]
26             }
27         ]
28     }
29 }
30 
31 response = requests.post(url, json=payload, headers=headers)
32 print(response.json())

In the body:

Name	Required	Type	Format	Description	Example
contract_id	true	string	-	Unique identifier of the contract for which the correction is being submitted	`3j5z2e6`
external_id	true	string	-	User-defined ID for the correction shift	`shift_example47`
description	true	string	-	Description of the correction. Use it to describe the reason for the correction.	`Correction shift`
shift_type	true	string	-	Type of shift being submitted. Use `CORRECTION_DELTA` for corrections	`CORRECTION_DELTA`
shift_reference_id	true	string	-	External ID of the original shift that is being corrected	`shift_example45`
corrections	true	array	-	Array containing correction details	-
corrections[].type	true	string	-	Type of correction. Use `SUBTRACTION` to reduce hours or `ADDITION` to add hours	`SUBTRACTION`
corrections[].time_amount	true	number	-	Amount of time to add or subtract from the original shift	`2.5`

Verify the response

A successful response (200) returns the details of the correction shift created.

1 {
2   "data": [
3     {
4       "external_id": "shift_example47",
5       "description": "Correction shift",
6       "date_of_work": "2019-08-24T14:15:22Z",
7       "contract_id": "3j5z2e6",
8       "summary": {
9         "time_amount": -2.5,
10         "total_payable_hours": -2.5
11       },
12       "shift_type": "CORRECTION_DELTA",
13       "shift_reference_id": "shift_example45",
14       "created_at": "2022-05-24T09:38:46.235Z",
15       "updated_at": "2022-05-24T09:38:46.235Z"
16     }
17   ]
18 }

Where:

Name	Required	Type	Format	Description	Example
external_id	true	string	-	User-defined ID of the correction shift	`shift_example47`
description	true	string	-	Description of the correction	`Correction shift`
date_of_work	true	string	date-time	Date of the original shift being corrected	`2019-08-24T14:15:22Z`
contract_id	true	string	-	Unique identifier of the contract	`3j5z2e6`
summary	true	object	-	Object containing the delta values for the correction. Negative values indicate reductions, positive values indicate additions.	-
summary.time_amount	true	number	-	Adjustment amount, negative for reduction and positive for increase	`-2.5`
shift_type	true	string	-	Type of shift, will be `CORRECTION_DELTA` for corrections	`CORRECTION_DELTA`
shift_reference_id	true	string	-	External ID of the original shift being corrected	`shift_example45`
created_at	true	string	date-time	Date on which the correction is created	`2022-05-24T09:38:46.235Z`
updated_at	true	string	date-time	Date on which the correction is updated	`2022-05-24T09:38:46.235Z`

Manage shift rates

Shift rates are used in payroll calculations to define the amount of salary to be paid for a specific shift. The shift rate types are:

Name	Description	Formula	Example
MULTIPLIER_PERCENTAGE	Defines the rate of a shift as a percentage of the salary, using the employee’s hourly salary (if it’s an hourly contract) or equivalent hourly salary (for non-hourly contracts).	`Total amount for shift = (MULTIPLIER_PERCENTAGE/100) * Per_hour_salary * Total_payable_hours`	10 $/hour is the base salary, user submitted shift with total of 5 payable hours and according to the shift rate attached to the shift MULTIPLIER_PERCENTAGE is set to 200% so Total amount paid for the shift = 2 * 10 * 5 = 100$
PER_HOUR_FLAT_RATE	Defines the rate of a shift as a flat rate per hour.	`Total amount for shift = PER_HOUR_FLAT_RATE * Total_payable_hours`	PER_HOUR_FLAT_RATE set to 100 $and total_payable_hours for the shift are 5 hours Total amount paid for the shift = 100 * 5 = 500$

Create a shift rate

You can create shift rates for your organization, which you can then map to individual shifts when adding them.

Make the request

Make a POST request to the time_tracking/shift_rates endpoint.

1 import requests
2 import os
3 
4 url = "https://api.letsdeel.com/rest/v2/time_tracking/shift_rates"
5 
6 headers = {
7     "Authorization": f"Bearer {os.getenv('DEEL_API_TOKEN')}",
8     "Content-Type": "application/json"
9 }
10 
11 payload = {
12     "data": {
13         "external_id": "regular_rate_1",
14         "name": "Regular Shift rate 1",
15         "type": "PER_HOUR_FLAT_RATE",
16         "value": 150
17     }
18 }
19 
20 response = requests.post(url, json=payload, headers=headers)
21 print(response.json())

In the body:

Name	Required	Type	Format	Description	Example
external_id	true	string	-	User defined unique identifier for the shift rate	`regular_rate_1`
name	true	string	-	A human readable string to identify the purpose of the shift rate	`Regular Shift rate 1`
type	false	string	ENUM	Defines the type of rate that must be used. Use any of the available shift rate types.	`PER_HOUR_FLAT_RATE`
value	false	number	-	Value of the shift rate, to use in combination with the `type` parameter	150

Retrieve a shift rate

You can retrieve a shift rate using the external_id of the shift rate.

Make the request

Make a GET request to the Retrieve a single time tracking shift rate endpoint.

1 import requests
2 import os
3 
4 external_id = "regular_rate_1"
5 url = f"https://api.letsdeel.com/rest/v2/time_tracking/shift_rates/{external_id}"
6 
7 headers = {
8     "Authorization": f"Bearer {os.getenv('DEEL_API_TOKEN')}",
9     "Content-Type": "application/json"
10 }
11 
12 response = requests.get(url, headers=headers)
13 print(response.json())

Where:

Name	Required	Type	Format	Description	Example
external_id	true	string	-	User-defined unique identifier for the shift rate	`shift_123456`

Review the response

A successful response (200) returns the shift rate of the requested shift.

1 {
2   "data": {
3     "organization_id": "string",
4     "external_id": "string",
5     "name": "string",
6     "rate_type": "MULTIPLIER_PERCENTAGE",
7     "value": 0,
8     "created_at": "2022-05-24T09:38:46.235Z",
9     "updated_at": "2022-05-24T09:38:46.235Z"
10   }
11 }

List shift rates

You can retrieve the list of shift rates for your organization.

Make the request

Make a GET request to the List time tracking shift rates endpoint.

1 import requests
2 import os
3 
4 url = "https://api.letsdeel.com/rest/v2/time_tracking/shift_rates"
5 
6 headers = {
7     "Authorization": f"Bearer {os.getenv('DEEL_API_TOKEN')}",
8     "Content-Type": "application/json"
9 }
10 
11 params = {
12     "limit": 10,
13     "offset": 5
14 }
15 
16 response = requests.get(url, headers=headers, params=params)
17 print(response.json())

Name	Required	Type	Format	Description	Example
limit	false	number		Number of rows that must be returned in one API call	100
offset	false	number		Number of rows that must be skipped when returning the results	10

Review the response

A successful response (200) returns the list of shift rates available in your organization and matching any filters applied.

1 {
2   "data": [
3     {
4       "organization_id": "string",
5       "external_id": "string",
6       "name": "string",
7       "rate_type": "MULTIPLIER_PERCENTAGE",
8       "value": 0,
9       "created_at": "2022-05-24T09:38:46.235Z",
10       "updated_at": "2022-05-24T09:38:46.235Z"
11     }
12   ],
13   "page": {
14     "total_rows": 0,
15     "items_per_page": 1,
16     "offset": 999999999
17   }
18 }

Where:

Name	Required	Type	Format	Description	Example
data	true	array	-	An array of shift rates	`[shift_rate_1, shift_rate_2, shift_rate_3]`
organization_id	true	number	-	The ID of your organization	`123456`
external_id	true	string	-	User defined unique identifier for the shift rate	`regular_rate_1`
name	true	string	-	A human readable string to identify the purpose of the shift rate	`Regular Shift rate 1`
rate_type	false	string	ENUM	Defines the type of rate that must be used. Use any of the available shift rates	`PER_HOUR_FLAT_RATE`
value	false	number	-	Value of the shift rate, to use in combination with the `type` parameter	150
created_at	true	string	date-time	Date on which the shift rate is created	`2022-05-24T09:38:46.235Z`
updated_at	true	string	date-time	Date on which the shift rate is updated	`2022-05-24T09:38:46.235Z`
page	true	object	-	An object containing pagination information. Use it to navigate through sets of	-

Update a shift rate

You can update a shift rate if it’s not being used in any shift, by using the external_id of the shift rate.

Only shift rates that are not used in any shift can be updated.

Make the request

Make a PATCH request to the Update a time tracking shift rate endpoint.

1 import requests
2 import os
3 
4 external_id = "regular_rate_1"
5 url = f"https://api.letsdeel.com/rest/v2/time_tracking/shift_rates/{external_id}"
6 
7 headers = {
8     "Authorization": f"Bearer {os.getenv('DEEL_API_TOKEN')}",
9     "Content-Type": "application/json"
10 }
11 
12 payload = {
13     "data": {
14         "name": "On-call shift rate",
15         "type": "PER_HOUR_FLAT_RATE",
16         "value": 150
17     }
18 }
19 
20 response = requests.patch(url, json=payload, headers=headers)
21 print(response.json())

In the path:

Name	Required	Type	Format	Description	Example
external_id	true	string	-	User defined unique identifier for the shift rate	`regular_rate_1`

In the body:

Name	Required	Type	Format	Description	Example
name	true	string	-	A human readable string to identify the purpose of the shift rate	`Regular Shift rate 1`
type	true	string	ENUM	Defines the type of rate that must be used. Use any of the available shift rates	`PER_HOUR_FLAT_RATE`
value	true	number	-	Value of the shift rate, to use in combination with the `type` parameter	150

Review the response

A successful response (200) returns the updated shift rate.

1 {
2   "data": {
3     "organization_id": "string",
4     "external_id": "string",
5     "name": "string",
6     "rate_type": "MULTIPLIER_PERCENTAGE",
7     "value": 0,
8     "created_at": "2022-05-24T09:38:46.235Z",
9     "updated_at": "2022-05-24T09:38:46.235Z"
10   }
11 }

Delete a shift rate

You can delete a shift rate if it’s not being used in any shift, by using the external_id of the shift rate.

Only shift rates that are not used in any shift can be deleted.

Make the request

Make a DELETE request to the Delete a time tracking shift rate endpoint.

1 import requests
2 import os
3 
4 external_id = "regular_rate_1"
5 url = f"https://api.letsdeel.com/rest/v2/time_tracking/shift_rates/{external_id}"
6 
7 headers = {
8     "Authorization": f"Bearer {os.getenv('DEEL_API_TOKEN')}",
9     "Content-Type": "application/json"
10 }
11 
12 response = requests.delete(url, headers=headers)
13 print(response.status_code)

Verify the response

A successful response (204) returns an empty body.

Next steps

Adjustments

Submit payroll adjustments for Global Payroll employees.

Global Payroll introduction

Overview of the Global Payroll API.

Before you begin

Retrieve your contract ID

Understand payroll cycles

Late shift behavior

Compensation calculation

Shift types

Categorized shifts

Uncategorized (raw) shifts

Shifts and payroll cycles

Preventing late submissions with payroll_cycle_ref.date

Format of the payroll_cycle_ref

Manage shifts

Add shifts

Add categorized shifts

Create a shift rate

Submit the shift

Verify the response

Add categorized shifts (Legacy)

Create a shift rate

Submit the shift

Verify the response

Add uncategorized (raw) shifts

Submit the shift

Verify the response

List shifts in your organization

Make the request

Review the response

Retrieve a single shift

Make the request

Review the response

Update shifts

Update categorized shift for an employee

Make the request

Review the response

Update uncategorized (raw) shift for an employee

Make the request

Review the response

Delete shift for a contract

Make the request

Verify the response

Correction shifts

Identify the shift to correct

Submit the correction

Verify the response

Manage shift rates

Create a shift rate

Make the request

Retrieve a shift rate

Make the request

Review the response

List shift rates

Make the request

Review the response

Update a shift rate

Make the request

Review the response

Delete a shift rate

Make the request

Verify the response

Next steps

Preventing late submissions with `payroll_cycle_ref.date`