Dates & Time zones

The golden rule

❗️

Do not include UTC offsets in your date values. The API calculates the correct offset automatically based on the workspace timezone and the specific date (including DST transitions).

Sending manual offsets (e.g., +02:00) can cause incorrect time shifts if the offset does not match the actual DST rules for that date.

Date and time formats overview

The smenso API does not use a single combined date-time format. Instead, date and time components are handled separately depending on the context:

📘

The smenso API accepts both European (dd.MM.yyyy) and ISO 8601 (yyyy-MM-dd) date formats for all input fields. Use whichever format your system produces natively.

Input: Date fields

All date input fields across the API accept two formats:

dd.MM.yyyy     (European format)
yyyy-MM-dd     (ISO 8601 format)

Examples:

• 15.09.2024 or 2024-09-15 → September 15, 2024
• 03.01.2025 or 2025-01-03 → January 3, 2025

Both formats are valid across all entities (Tasks, Projects, Absences, Time Records, Status Reports) and apply to fields like startDate, endDate, dueDate, Start, End, and similar.

❗️

Do not append times to date values. While the API may technically accept a time component (e.g., 15.09.2024 08:00), this leads to unexpected behavior - especially when tasks are rescheduled or moved. For Tasks, the system automatically applies 00:00 for start dates and 23:59 for end dates. Always send date-only values.

📘

Which format should I use? Both work equally well. If your system already produces ISO 8601 dates, you can use them directly - no conversion needed. The API examples in this documentation primarily use dd.MM.yyyy, but yyyy-MM-dd is fully supported.

Input: Partial day absences (startDateMinutes / endDateMinutes)

When an absence does not cover full days at the beginning or end, you can specify how many minutes the person is absent on the first and/or last day using startDateMinutes and endDateMinutes. These fields represent absence duration on that day, not a time of day.

• If the first or last day is a full absence day, simply omit these fields.
• If the first or last day is a partial absence day, set the value to the number of minutes absent on that day.

Example: Full-day absence

For a full-day absence, you only need the start and end date - no minute fields required:

{
  "userId": "{user-guid}",
  "absenceTypeId": "{type-guid}",
  "startDate": "16.02.2026",
  "endDate": "16.02.2026"
}

Example: Absence with partial first and last day

A person with an 8-hour workday (480 minutes) takes time off from March 16 to March 18, but only half a day on the first and last day:

{
  "userId": "{user-guid}",
  "absenceTypeId": "{type-guid}",
  "startDate": "16.03.2026",
  "endDate": "18.03.2026",
  "startDateMinutes": 240,
  "endDateMinutes": 240
}

This results in:

• March 16 → half day absent (240 min = 4 hours)
• March 17 → full day absent
• March 18 → half day absent (240 min = 4 hours)
• Total → 2 workdays of absence

Input: Duration fields

Duration values are expressed in minutes as integers:

This applies to fields like duration, plannedDuration on Tasks, and duration on Absences.

Input: Date flavors - two accepted formats

For Flavor fields of type "Date," the API accepts two input formats:

⚠️

Milliseconds, not seconds: Make sure you send Unix timestamps in milliseconds. If your system uses seconds, multiply by 1000. For example: 1726790400 seconds → 1726790400000 milliseconds.

XML example

<!-- Standard date format -->
<Flavor target="{flavor-guid}">20.09.2024</Flavor>

<!-- Unix timestamp in milliseconds -->
<Flavor target="{flavor-guid}">1726790400000</Flavor>

JSON example

{
  "flavors": [
    { "target": "{flavor-guid}", "value": "20.09.2024" },
    { "target": "{flavor-guid}", "value": "1726790400000" }
  ]
}

Output: Date values in responses

Integration API responses

The Integration API returns dates in a fixed format:

Date-only fields use dd.MM.yyyy:

"startDate": "16.02.2026"

Date + time fields use dd.MM.yyyy HH:mm:ss:

"Updated On": "15.07.2025 14:54:43"

Reporting API responses

The Reporting API output format is controlled by the lang query parameter appended to the URL:

# German format
&lang=de    →  15.07.2025  /  15.07.2025 14:54:43

# English format
&lang=en    →  07/15/2025  /  07/15/2025 2:54:43 PM

📘

If no lang parameter is provided, the Reporting API uses the workspace's default language. Always set lang explicitly in your integration to ensure consistent date formats in the output.

Default timezone behavior

• The workspace default timezone is W. Europe Standard Time (CET/CEST with automatic DST handling).
• The API automatically handles summer/winter time (DST) transitions.
• For a date in January (CET): the API applies UTC+1.
• For a date in July (CEST): the API applies UTC+2.

You do not need to handle DST logic in your integration - the API does it for you.

Overriding the timezone

If your integration needs a different timezone (e.g., for users in a different region), you can specify it explicitly.

Retrieving supported timezone identifiers

Before specifying a timezone, retrieve the list of supported identifiers:

The response returns identifiers like W. Europe Standard Time, Romance Standard Time, etc.

📘

Always use the exact identifiers returned by the Timezones endpoint. Do not use IANA identifiers (e.g., Europe/Berlin) unless confirmed by the endpoint.

XML: timezoneId attribute on the root element

<!-- Without timezone (uses workspace default) -->
<Tasks projectId="{project-guid}">
  <Task>
    <StartDate>15.09.2024</StartDate>
  </Task>
</Tasks>

<!-- With explicit timezone -->
<Tasks projectId="{project-guid}" timezoneId="Romance Standard Time">
  <Task>
    <StartDate>15.09.2024</StartDate>
  </Task>
</Tasks>

JSON: timezone field in the request

{
  "timezoneId": "Romance Standard Time",
  "startDate": "15.09.2024"
}

Template endpoints (XML)

Template-related XML calls support both timezoneId and lang:

<Template timezoneId="W. Europe Standard Time" lang="de">
  <ProjectBase>
    <StartDate>05.09.2024</StartDate>
    <Title>My Project</Title>
  </ProjectBase>
</Template>

Common pitfalls