> ## Documentation Index
> Fetch the complete documentation index at: https://developers.luccasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Replace ShiftOverrides for an employee.
> Replace all ShiftOverrides for a given employee within the specified date range.
This endpoint uses a PUT semantic: all existing ShiftOverrides for the employee within
the `startsAt.between` range will be removed and replaced by the ones provided in the
request body. If none exist, then the provided ShiftOverrides will simply be created.
Both `employee.id` and `startsAt.between` query parameters are required.
## OpenAPI
````yaml /openapi-specs/schedule.yaml put /schedule/api/shift-overrides
openapi: 3.1.0
info:
title: Time Settings API
version: '1.0'
description: |
Welcome on the documentation for the Time Settings API.
contact:
name: API Support
url: https://www.luccasoftware.com
email: no-reply@luccasoftware.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://{host}
description: Your Lucca account URL.
variables:
host:
default: example.ilucca.net
description: >-
The URL of your dedicated Lucca account: `{account}.{env}.{region}`.
Account reflects your company name. Env indicates the environment.
Region depends on your server location.
**Please, use your test or sandbox environments (and not your
production env.) for testing purposes.**
Environments:
- `ilucca`: production environment for customers.
- `ilucca-test`: test environment for customers.
- `ilucca-demo`: demo environment for prospects.
Regions:
- `.ch` for Swiss located accounts.
- `.net` for the others.
Regarding sandboxes, the pattern differs:
`https://{account}-{sandboxName}.sandbox.{server}.luccasoftware.com`,
where:
- `{sandboxName}` is automatically generated upon creation.
- `{server}` may be "eu1", "eu2" or "ch1".
security: []
tags:
- name: UserDates
description: Aggregates work schedule events.
- name: WorkCycleExceptions
description: Override an employee's theoretical working hours.
- name: Working Time Arrangements
description: Employees recurring working hours.
- name: Collective Schedules
description: Describes the working hours pattern of a working-time-arrangement.
- name: employee-assignments
description: Assignations of employees to working time arrangements.
- name: ShiftOverrides
description: One-time overrides of an employee's regular work schedule.
paths:
/schedule/api/shift-overrides:
parameters:
- $ref: '#/components/parameters/Authorization'
put:
tags:
- ShiftOverrides
summary: Replace ShiftOverrides for an employee.
description: >
Replace all ShiftOverrides for a given employee within the specified
date range.
This endpoint uses a PUT semantic: all existing ShiftOverrides for
the employee within
the `startsAt.between` range will be removed and replaced by the ones
provided in the
request body. If none exist, then the provided ShiftOverrides will
simply be created.
Both `employee.id` and `startsAt.between` query parameters are
required.
operationId: put-shift-overrides
parameters:
- name: employee.id
in: query
required: true
description: The ID of the employee whose ShiftOverrides should be replaced.
schema:
type: integer
format: int32
minimum: 0
- name: startsAt.between
in: query
required: true
description: >
The date range within which existing ShiftOverrides will be
replaced.
Open-ended ranges can be defined with `..` characters.
schema:
type: string
examples:
- 2023-01-01--2023-01-31
- ..--2023-01-01
- 2023-01-01--..
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ShiftOverrideCandidate'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/ShiftOverride'
'400':
$ref: '#/components/responses/ResponseProblem'
'401':
$ref: '#/components/responses/ResponseProblem'
'500':
$ref: '#/components/responses/ResponseProblem'
components:
parameters:
Authorization:
name: Authorization
required: true
description: 'API key. Value must be formatted like so: `lucca application={api_key}`.'
in: header
schema:
type: string
schemas:
ShiftOverrideCandidate:
title: ShiftOverrideCandidate
type: object
description: |
Data required to create a ShiftOverride.
required:
- employeeId
- position
- startsAt
- duration
- nature
properties:
employeeId:
type: integer
format: int32
minimum: 0
description: The ID of the employee this override applies to.
position:
$ref: '#/components/schemas/DayPosition'
startsAt:
type: string
format: date-time
description: Start date-time of the override.
duration:
$ref: '#/components/schemas/ShiftOverrideDuration'
nature:
$ref: '#/components/schemas/ShiftOverrideNature'
comment:
type:
- 'null'
- string
description: Optional comment associated with the override.
ShiftOverride:
title: ShiftOverride
type: object
description: >
Represents a one-time override of an employee's regular work schedule
for a specific period.
required:
- id
- employee
- position
- startsAt
- endsAt
- duration
- workCycleUnit
- nature
- isLocked
- createdAt
- lastUpdatedAt
properties:
id:
type: integer
format: int32
minimum: 0
description: Unique identifier of the ShiftOverride.
employee:
type: object
description: The employee this override applies to.
properties:
id:
type: integer
format: int32
minimum: 0
position:
$ref: '#/components/schemas/DayPosition'
startsAt:
type: string
format: date-time
description: Start date-time of the override.
endsAt:
type: string
format: date-time
description: End date-time of the override.
duration:
$ref: '#/components/schemas/ShiftOverrideDuration'
workCycleUnit:
$ref: '#/components/schemas/ShiftOverrideEventUnit'
nature:
$ref: '#/components/schemas/ShiftOverrideNature'
comment:
type:
- 'null'
- string
description: Optional comment associated with the override.
isLocked:
type: boolean
description: Whether the override is locked (cannot be modified).
createdAt:
type: string
format: date-time
description: Date-time when the override was created.
createdBy:
type:
- 'null'
- object
description: The user who created the override.
properties:
id:
type: integer
format: int32
minimum: 0
lastUpdatedAt:
type: string
format: date-time
description: Date-time when the override was last updated.
lastUpdatedBy:
type:
- 'null'
- object
description: The user who last updated the override.
properties:
id:
type: integer
format: int32
minimum: 0
DayPosition:
title: DayPosition
type: string
enum:
- firstHalf
- secondHalf
- fullDay
ShiftOverrideDuration:
title: Duration
type: object
description: The duration of the override.
required:
- unit
- value
- iso
properties:
unit:
type: string
enum:
- days
- hours
description: The unit in which the duration value is expressed.
value:
type: number
format: decimal
minimum: 0
description: The numeric duration value.
readOnly: true
iso:
type: string
description: ISO 8601 duration representation.
ShiftOverrideNature:
title: ShiftOverrideNature
type: string
description: |
The nature of the shift override.
- `worked`: the employee is working.
- `off`: the employee is off.
- `partTime`: part-time day.
- `weeklyRest`: weekly rest day.
enum:
- worked
- 'off'
- partTime
- weeklyRest
ShiftOverrideEventUnit:
title: EventUnit
type: string
description: |
The unit of the work cycle for this override.
- `day`: duration expressed in days.
- `hour`: duration expressed in hours.
- `time`: duration expressed in hours with a specific start time.
enum:
- day
- hour
- time
responses:
ResponseProblem:
description: Problem
content:
application/json:
schema:
type: object
properties:
Status:
type: integer
description: HTTP status code.
example: 401
Message:
type: string
description: Human readable error message.
example: Unauthorized
````