ProjectsRegister time on a task (for yourself)

Register time on a task (for yourself)

Registers project time for the authenticated user on one task and date.

The short form of time registration used by the TAF action add-registration on every task entity: no ID, no UserID, no GroupType. The registration is always for the caller, always project time (GroupType 1) in hours; the server generates its GUID. Unlike POST /v1/time-registration, the response body is the literal JSON null — the new registration's ID is not returned, so the only way to find it is to list your registrations afterwards. If the caller is not yet allocated to the task, TimeLog creates the allocation first.

Use it to:

  • Quick registration from a task picker (search-for-time-tracking → add-registration)

Not for:

  • Registering for another user, absence or travel-time group type, or when you need the created ID → POST /v1/time-registration
  • Import with project/contract and an hourly-rate override → POST /v1/time-registration/import

Rules across fields:

  • R1: StartTime and EndTime both sent → EndTime > StartTime and whole minutes between them = round(Hours × 60).

Behaviour:

  • Not idempotent.
  • Not safe to retry blindly. Each call generates a new GUID: a retry after a timeout creates a second registration. List the caller's registrations before retrying.
  • Duplicates: Never deduplicated: the GUID is server-generated per call.
  • Side effect: If the caller is not allocated to the task: adds the caller to the project's resource group and contract team and creates a 0-hour allocation — BEFORE business-rule validation and outside the save transaction, so it persists when the registration is rejected.
  • Side effect: Creates the work unit; updates invoicing potential, salary posting and mileage links; recalculates financial data after commit (pilot trace).
  • Read-after-write consistency: not yet documented.

Call first: GET /v1/task/search-for-time-tracking, GET /v1/task/get-recently-registered

See also: POST /v1/time-registration

Not yet documented: behaviour → consistency; examples; request → body.

curl -X POST "https://app3.timelog.com/your-account/api/v1/task/registration" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
  "TaskID": 123,
  "Date": "2024-12-25T10:00:00Z",
  "Hours": 3.14,
  "Minutes": 42,
  "Billable": true,
  "BillableHours": 3.14,
  "BillableMinutes": 42,
  "Factor": 3.14,
  "Comment": "null",
  "AdditionalComment": "example_string",
  "MonthlyPeriod": "example_string",
  "StartTime": "2024-12-25T10:00:00Z",
  "EndTime": "2024-12-25T10:00:00Z"
}'
"null"
POST
/v1/task/registration
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
TaskIDinteger
Required

The task the time is registered on. Refers to TaskRead.TaskID. Look up valid values with GET /v1/task/search-for-time-tracking. - The caller is not allocated to the task — TimeLog CREATES the allocation (adds the caller to the project resource group and contract team, 0-hour allocation) before the registration's business rules run; it persists even if the registration is then rejected. Valid values come from GET /v1/task/search-for-time-tracking.

Format: int32
Datestring
Required

The date the time is registered on. Time zone: not yet documented. Stored as sent. Send midnight (YYYY-MM-DDT00:00:00). The default 0001-01-01 counts as empty (400). > Not yet documented: constraints → timezone.

Format: date-time
Hoursnumber
Required

Duration in decimal hours (e.g. 1.5 = 1 h 30 min). Unit: hours (decimal) Must be > 0 (stricter than the pilot create, which only rejects 0). Range: min > 0, unit hours (decimal).

Format: double
Minutesinteger

Duration in minutes. Unit: minutes - always — Hours is always passed (and must be > 0), and Hours wins over Minutes for project time — Minutes is never applied.

Format: int32
Billableboolean

Whether the time is billable to the customer. - Feature BillableOnTime is OFF — Set to the task's billable flag. - Task is fixed-price and the resulting Billable is false — Fails with 37620 (rest.timeregistration.fixed-price-non-billable).

BillableHoursnumber

Billable duration in decimal hours. Unit: hours (decimal) - The registration ends up non-billable — ignored - Task is fixed-price and feature BillableHoursIsEditableOnFixedPrice is OFF — Set to Hours. - Feature BillableHoursIsEditable is OFF — Set to the actual Hours (pilot trace). - Billable and the field is omitted (other cases) — 0 billable hours is stored. - Feature RoundingOfBillableTime is ON — A mismatch raises 30168.

Format: double
BillableMinutesinteger

Billable duration in minutes. Unit: minutes - always — BillableHours is always passed (0 when omitted), so BillableMinutes is never applied.

Format: int32
Factornumber

Registration factor in percent (100 = normal). Unit: percent Default: 0 on the wire → stored as 100 - Feature OvertimeFactor is OFF, or the task is fixed-price — Always 100. - OvertimeFactor ON and value is in the setting RoundingFactorOptionOfTimeRegistrations — applied - OvertimeFactor ON, value not in the list — Stored as 100.

Format: double
Commentstringnull

Free-text comment on the registration. - Feature MandatoryComment is ON and comment is empty — Fails with 300116. > Not yet documented: constraints → max length.

AdditionalCommentstring

Second free-text field; its title and validation are site settings (captured title "Support ticket number", validation Number). Conditional. Required when the site configures the additional field as mandatory (30048).

MonthlyPeriodstring

Salary month the registration belongs to, as MMyyyy. - Feature TempTreatAllTimeRegistrationAsRecurringTask is OFF — ignored - Value outside ±MonthlyPeriodDropdownRange months of today, or malformed — Returns 500 (Code 100), not 400.

StartTimestring

Start time of the work. Time zone: none applied — sent value stored as-is - The caller does not have timestamps enabled — StartTime/EndTime are cleared. - Timestamps enabled, StartTime sent — Seconds dropped; no timezone conversion; the stored end = StartTime + Hours. - Timestamps enabled, no StartTime — End = the caller's current time on that date, start = end − Hours (midnight-anchored if that crosses the previous day).

Format: date-time
EndTimestring

End time of the work — used only to cross-check StartTime and Hours. Time zone: none applied — only compared with StartTime - StartTime and EndTime both sent — 400 unless EndTime > StartTime and the whole minutes between them equal round(Hours × 60). - always — Never passed to the save: the stored end time is computed from StartTime + Hours.

Format: date-time
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
TaskIDinteger
Required

The task the time is registered on.

Refers to TaskRead.TaskID. Look up valid values with GET /v1/task/search-for-time-tracking.

  • The caller is not allocated to the task — TimeLog CREATES the allocation (adds the caller to the project resource group and contract team, 0-hour allocation) before the registration's business rules run; it persists even if the registration is then rejected.

Valid values come from GET /v1/task/search-for-time-tracking.

Datestring
Required

The date the time is registered on.

Time zone: not yet documented.

Stored as sent. Send midnight (YYYY-MM-DDT00:00:00). The default 0001-01-01 counts as empty (400).

Not yet documented: constraints → timezone.

Hoursnumber
Required

Duration in decimal hours (e.g. 1.5 = 1 h 30 min).

Unit: hours (decimal)

Must be > 0 (stricter than the pilot create, which only rejects 0).

Range: min > 0, unit hours (decimal).

Minutesinteger

Duration in minutes.

Unit: minutes

  • always — Hours is always passed (and must be > 0), and Hours wins over Minutes for project time — Minutes is never applied.
Billableboolean

Whether the time is billable to the customer.

  • Feature BillableOnTime is OFF — Set to the task's billable flag.

  • Task is fixed-price and the resulting Billable is false — Fails with 37620 (rest.timeregistration.fixed-price-non-billable).

BillableHoursnumber

Billable duration in decimal hours.

Unit: hours (decimal)

  • The registration ends up non-billable — ignored

  • Task is fixed-price and feature BillableHoursIsEditableOnFixedPrice is OFF — Set to Hours.

  • Feature BillableHoursIsEditable is OFF — Set to the actual Hours (pilot trace).

  • Billable and the field is omitted (other cases) — 0 billable hours is stored.

  • Feature RoundingOfBillableTime is ON — A mismatch raises 30168.

BillableMinutesinteger

Billable duration in minutes.

Unit: minutes

  • always — BillableHours is always passed (0 when omitted), so BillableMinutes is never applied.
Factornumber

Registration factor in percent (100 = normal).

Unit: percent

Default: 0 on the wire → stored as 100

  • Feature OvertimeFactor is OFF, or the task is fixed-price — Always 100.

  • OvertimeFactor ON and value is in the setting RoundingFactorOptionOfTimeRegistrations — applied

  • OvertimeFactor ON, value not in the list — Stored as 100.

Commentstring,null

Free-text comment on the registration.

  • Feature MandatoryComment is ON and comment is empty — Fails with 300116.

Not yet documented: constraints → max length.

AdditionalCommentstring

Second free-text field; its title and validation are site settings (captured title "Support ticket number", validation Number).

Conditional. Required when the site configures the additional field as mandatory (30048).

MonthlyPeriodstring

Salary month the registration belongs to, as MMyyyy.

  • Feature TempTreatAllTimeRegistrationAsRecurringTask is OFF — ignored

  • Value outside ±MonthlyPeriodDropdownRange months of today, or malformed — Returns 500 (Code 100), not 400.

StartTimestring

Start time of the work.

Time zone: none applied — sent value stored as-is

  • The caller does not have timestamps enabled — StartTime/EndTime are cleared.

  • Timestamps enabled, StartTime sent — Seconds dropped; no timezone conversion; the stored end = StartTime + Hours.

  • Timestamps enabled, no StartTime — End = the caller's current time on that date, start = end − Hours (midnight-anchored if that crosses the previous day).

EndTimestring

End time of the work — used only to cross-check StartTime and Hours.

Time zone: none applied — only compared with StartTime

  • StartTime and EndTime both sent — 400 unless EndTime > StartTime and the whole minutes between them equal round(Hours × 60).

  • always — Never passed to the save: the stored end time is computed from StartTime + Hours.

Responses

Success without content: HTTP 200 with the literal JSON body null. Body is the literal JSON null (TafSuccessResult). No ID, no Location header.