Time records in smenso represent logged working time for users, typically booked against tasks and projects. They are the basis for workload analysis, utilization reporting and controlling.

A time record usually contains:

• the user who recorded the time
• the date
• either a duration or a start and end time
• the related task and project
• optional attributes like description, activity type, billability, or flavors (custom metadata)

Time records appear in timesheets, task views, project reports, and workload/capacity visualizations. They help answer questions like: Who worked on what, when, and for how long?

Duration vs Start/End Time

A time record can be described either by:

• a duration (e.g. 4 hours), or
• a start time and end time (e.g. 09:00–13:00)

If start and end time are provided, the system calculates the duration. If a duration is provided, start and end time are either optional or cleared.

This ensures a clear, unambiguous representation of the booked time.

Validation & Constraints

Time recording follows the same constraints as in the UI. Common rules include:

• Project and task state
  • Time cannot be recorded on archived or inactive projects.
  • Time cannot be recorded on project templates.
  • If a project or task has time recording blocked, new records are rejected.
• Date consistency
  • The booking date must be valid, and the duration or time range must be non-negative.
• Access & Permissions
  • Users can only record or edit time if their role and workspace permissions allow it.

Time Records & Flavors

Time records can carry flavors (custom fields) for additional categorization such as:

• cost centers
• activity types
• internal/external flags
• billing categories

These values can be used in reports, exports, and downstream integrations.

Time Records Across the APIs

JSON API

• Provides modern endpoints for time recording use cases
• Uses the same business rules as the UI

XML Integration API

• Supports creating and updating time records via XML requests
• Applies validation rules consistently across batch operations

Reporting API

• Provides read-only exports of booked time based on configured views
• Commonly used for analytics, controlling, and billing exports

Available Endpoints

Integration JSON API (read & write)

📘

Create and update requests are processed asynchronously. The response contains a status ticket id that you poll via GET /api/integration/status/json/{ticketId}. See Integration Tickets.

Key Fields

For the full schema, see the API reference of each endpoint.

📘

An update request can change duration, startDate, endDate, description, statusId, locked, and flavor. It does not contain userId, taskId, or date.

Create Time Records

POST /api/integration/timerecord/json
Content-Type: application/json
Authorization: Basic {YOUR_TOKEN}

{
  "timezoneId": "W. Europe Standard Time",
  "projectId": "4f9c2b2e-1234-5678-9abc-0a1b2c3d4e5f",
  "timeRecord": [
    {
      "tempId": 1,
      "taskId": "<task id>",
      "userId": "[email protected]",
      "date": "2026-11-02",
      "duration": 240,
      "description": "Workshop preparation"
    }
  ]
}

The response contains a status ticket ID. Poll the ticket to get the result. Use tempId to match your input rows to the created time records, as described in the Tasks guide.

📘

For dates and times, see Dates & Time zones. Use timezoneId to define the time zone of the values you send.

Update Time Records

PUT /api/integration/timerecord/json
Content-Type: application/json
Authorization: Basic {YOUR_TOKEN}

{
  "projectId": "4f9c2b2e-1234-5678-9abc-0a1b2c3d4e5f",
  "timeRecord": [
    {
      "id": "<time record id>",
      "duration": 90,
      "statusId": 1
    }
  ]
}

📘

Update by externalId: set useExternalId to true and put the external ID into id.

Get Time Records

GET /api/integration/timerecord/json/{projectId}?lang=en&timezone=W. Europe Standard Time
Authorization: Basic {YOUR_TOKEN}

Each time record contains the fields id, projectId, projectCode, projectName, taskId, taskCode, taskName, user, date, startDate, endDate, duration, description, billing, hourlyRate, actualCost, locked, dateCreated, createdBy, dateUpdated, and updatedBy.

For large evaluations across projects, use the Reporting API exports instead.

Delete a Time Record

DELETE /api/integration/timerecord/json/{timeRecordId}
Authorization: Basic {YOUR_TOKEN}

FAQ

In which unit is duration sent?

In minutes. For example, 240 means four hours.

Can I use an email address instead of a user ID?

Yes. userId accepts the ID or the email address of the user.

Why is my time record rejected?

Time recording follows the same rules as the UI: for example, time cannot be booked on archived projects, on templates, or on tasks and projects with blocked time recording. See Validation & Constraints above. If a request fails, the details are available in the status ticket.

Summary

Time records represent booked working time in smenso and are used for utilization and reporting. They can be recorded using duration or start/end times, are subject to project/task restrictions, and follow workspace permissions across all API types.