Time registrationsStart a time tracker on an absence code

Start a time tracker on an absence code

Starts a stopwatch for the calling user on an absence code.

Creates a running, non-billable time tracker for the authenticated user on AbsenceCodeID, starting now (server clock). Any running tracker of the caller is stopped first and converted into a time registration. With TimeRegistrationID, comment, additional text, factor and monthly period are copied from that registration and the tracker is linked to it when it is dated today; the absence code always comes from AbsenceCodeID. Returns the new tracker.

Behaviour:

  • Not idempotent.
  • Not safe to retry blindly.
  • Side effect: Stops the caller's running tracker (if any) and converts it into time registration(s).
  • Side effect: Creates the tracker (TimeTrackerCreated event); notifies invoicing potential.
  • Changes are visible to the next read immediately.

Next: POST /v1/time-registration/stop-time-tracker/{timeTrackerId}, GET /v1/time-tracker/active-time-tracker

Not yet documented: behaviour (linked project registration); examples (success).

curl -X POST "https://app3.timelog.com/your-account/api/v1/time-tracker/absence/start-time-tracker" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
  "AbsenceCodeID": 123,
  "TimeRegistrationID": "null",
  "Minute": 42,
  "Comment": "null"
}'
{
  "Properties": {
    "TimeTrackerID": 123,
    "ID": "123e4567-e89b-12d3-a456-426614174000",
    "UserID": 123,
    "Date": "2024-12-25T10:00:00Z",
    "StartTime": "2024-12-25T10:00:00Z",
    "EntityType": 42,
    "EntityID": "null",
    "Task": {
      "TaskID": 123,
      "ID": "123e4567-e89b-12d3-a456-426614174000",
      "Name": "John Doe",
      "No": "example_string",
      "IsFixedPrice": true,
      "IsDefaultBillable": true,
      "AdditionalTextIsRequired": true,
      "ParentFullName": "John Doe",
      "ProjectID": 123,
      "Project": {
        "ProjectID": 123,
        "ID": "123e4567-e89b-12d3-a456-426614174000",
        "Name": "John Doe",
        "No": "example_string",
        "ExpenseIsBillable": "null",
        "CustomerID": 123,
        "Customer": {
          "CustomerID": 123,
          "ID": "123e4567-e89b-12d3-a456-426614174000",
          "Name": "John Doe",
          "No": "example_string",
          "DefaultMileageDistance": 25,
          "CustomerStatusID": 123,
          "VATNo": "example_string",
          "OrganizationNo": "example_string"
        },
        "MainContractId": 123
      },
      "ParentTaskID": "null",
      "IsTravelTimeTask": true,
      "IsFavourite": "null"
    },
    "AbsenceCode": {
      "AbsenceCodeID": 123,
      "AbsenceCode": "example_string",
      "Name": "John Doe",
      "Description": "example_string",
      "IsActive": true,
      "FlexPositiveFactor": 3.14,
      "SalaryAccountFactor": 3.14,
      "SalaryAccountFactorEffect": 10,
      "SalaryAccountID": 123,
      "AbsenceCodeTypeID": 123,
      "DeductCapacity": true,
      "TimeTrackingFormat": 42,
      "RequireApproval": true,
      "IsPublicVisible": true,
      "IsFavourite": "null",
      "ID": "123e4567-e89b-12d3-a456-426614174000"
    },
    "TimeRegistrationID": "null",
    "Comment": "example_string",
    "Minute": 42,
    "BillableMinute": 42,
    "IsBillable": "null",
    "TimeTrackerStatus": 42,
    "MonthlyPeriod": "null",
    "AdditionalTextField": "null",
    "Factor": 3.14
  },
  "Links": [
    {
      "Href": "example_string",
      "Rel": "example_string"
    }
  ],
  "Actions": [
    {}
  ]
}
POST
/v1/time-tracker/absence/start-time-tracker
POST
Base URLstring

Target server for requests. Edit to use your own host.

Bearer Token
Bearer Tokenstring
Required

OAuth 2.0 bearer token, sent as Authorization: Bearer <token>. JWT and reference tokens are both accepted. The token must carry the required scope (default tlp). The token's sub claim is the acting user. A token WITHOUT sub (client-credentials) acts as the system service user. If the sub user cannot log in (inactive, locked, deleted), the request is rejected with 401 — it is no longer let through without a user. > Not yet documented: how to obtain a token. > Not yet documented: token lifetime.

OAuth 2.0 bearer token, sent as Authorization: Bearer <token>. JWT and reference tokens are both accepted. The token must carry the required scope (default tlp). The token's sub claim is the acting user. A token WITHOUT sub (client-credentials) acts as the system service user. If the sub user cannot log in (inactive, locked, deleted), the request is rejected with 401 — it is no longer let through without a user. > Not yet documented: how to obtain a token. > Not yet documented: token lifetime.
Content-Typestring
Required

The media type of the request body

Options: application/json
AbsenceCodeIDinteger
Required

The absence code to track. Always used, also when TimeRegistrationID is sent (it replaces the registration's entity). Refers to AbsenceCodeRead.AbsenceCodeID.

Format: int32
TimeRegistrationIDintegernull

Start from an existing registration: copies comment, additional text, factor and monthly period, and LINKS the tracker when the registration is dated today (server date). Refers to TimeRegistrationRead.TimeRegistrationID. Look up valid values with GET /v1/time-registration/{timeRegistrationID}.

Format: int32
Minuteinteger

Minutes already counted before now. With TimeRegistrationID and a value > 0: the expected total. Unit: minutes

Format: int32
Commentstringnull

- Always — Overwrites the tracker comment, including the registration's comment when TimeRegistrationID is sent and Comment is omitted.

Request Preview
Response

Response will appear here after sending the request

Authentication

header
Authorizationstring
Required

Bearer token. OAuth 2.0 bearer token, sent as Authorization: Bearer <token>. JWT and reference tokens are both accepted. The token must carry the required scope (default tlp).

The token's sub claim is the acting user. A token WITHOUT sub (client-credentials) acts as the system service user. If the sub user cannot log in (inactive, locked, deleted), the request is rejected with 401 — it is no longer let through without a user.

Not yet documented: how to obtain a token.

Not yet documented: token lifetime.

Body

application/json
AbsenceCodeIDinteger
Required

The absence code to track. Always used, also when TimeRegistrationID is sent (it replaces the registration's entity).

Refers to AbsenceCodeRead.AbsenceCodeID.

TimeRegistrationIDinteger,null

Start from an existing registration: copies comment, additional text, factor and monthly period, and LINKS the tracker when the registration is dated today (server date).

Refers to TimeRegistrationRead.TimeRegistrationID. Look up valid values with GET /v1/time-registration/{timeRegistrationID}.

Minuteinteger

Minutes already counted before now. With TimeRegistrationID and a value > 0: the expected total.

Unit: minutes

Commentstring,null
  • Always — Overwrites the tracker comment, including the registration's comment when TimeRegistrationID is sent and Comment is omitted.

Responses

Propertiesobject

A time tracker (stopwatch) of one employee. A tracker is either running (TimeTrackerStatus 1) or ended but not yet turned into a time registration (TimeTrackerStatus 2). When a tracker is stopped and its data forms a valid registration, the registration is written and the tracker row is deleted, so a tracker is short-lived.

Linksarray
Actionsobject[]