ProjectsChange the status of several projects

Change the status of several projects

Moves every listed project to one status (Quote … Cancelled), one project after another.

For each ID in projectsIds, in the order given: loads the project, changes its status with TimeLog's status processing and saves it. InProgress opens the project for time registration; OnHold / Completed / Archived / Cancelled close it; Quote / Approved keep the project's current flag. Completed, Archived and Cancelled also mark every open milestone completed and move every open contract to Completed (Cancelled for Cancelled) — reopening later does NOT reopen contracts. Answers 200 with an empty TAF list whose Properties.UpdatedProjectsCount is the number of IDs processed. The first failing project aborts the call with 500 and the earlier projects KEEP their new status; there is no per-project result. Always send Status: {} moves every listed project to Quote.

Use it to:

  • Close a batch of finished projects (Completed / Archived) from a portfolio tool

Not for:

  • Opening a Quote / Approved project for time registration — this route keeps the current flag; use PUT /v1/project/{projectID}/status (AllowTimeTracking)

Rules across fields:

  • R1: When the projectsIds string is exactly one character long (a single project 1–9), Date is replaced by today.

Behaviour:

  • Idempotent.
  • Same status again re-applies it: status date reset, ProjectStatusChanged raised again, project re-saved.
  • Safe to retry only under a condition. After a 500 re-send the whole list: projects already moved are re-applied harmlessly; closing statuses never reopen contracts, so a retry cannot undo the cascade.
  • Side effect: Per project: status units / status date written and the status stored, OpenForTimeRegistration set by status.
  • Side effect: Completed / Archived / Cancelled: open milestones completed, every open contract moved to Completed / Cancelled.
  • On failure: Projects before the failing one keep their new status; within the failing project the status may already be written before the save fails.
  • Changes are visible to the next read immediately.
  • Batch: Sequential, no transaction, no per-item result: the first failure aborts the rest with 500 and gives no indication which projects were already changed.

Call first: GET /v2/projects, GET /v2/projects/actions

See also: PUT /v1/project/{projectID}/status

Not yet documented: errors; examples.

curl -X PUT "https://app3.timelog.com/your-account/api/v2/projects/status?projectsIds=example_string" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
  "Status": 42,
  "Date": "null"
}'
{
  "Properties": {
    "UpdatedProjectsCount": "example_string"
  },
  "Links": [
    {
      "Href": "example_string",
      "Rel": "example_string"
    }
  ],
  "Actions": [
    {}
  ]
}
PUT
/v2/projects/status
PUT
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.
query
projectsIdsstring
Required

Comma-separated project IDs, processed in order; duplicates are processed (and counted) twice. Omitted → 405 (captured). A non-integer entry → 500 after the entries before it were applied. Several values: one string, separated by ,.

Content-Typestring
Required

The media type of the request body

Options: application/json
Statusinteger

The new status, as the OrderStatus integer. Non-nullable: when omitted it arrives as 0 and is APPLIED — {} moves every listed project to Quote. - Not one of 0–6 — 400 "Status must be 0 = Quote or 1 = Approved or 2 = InProgress or 3 = OnHold or 4 = Completed or 5 = Archived or 6 = Cancelled." - Omitted — 0 = Quote is applied. - Quote or Approved — OpenForTimeRegistration is left as the project had it (the controller passes the project's own flag). Allowed values: | Value | Name | Meaning | |---|---|---| | 0 | Quote | Quote. Time registration keeps the project's current open/closed flag. | | 1 | Approved | Approved. Time registration keeps the project's current open/closed flag. | | 2 | InProgress | In progress. Opens the project for time registration. | | 3 | OnHold | On hold. Closes the project for time registration. | | 4 | Completed | Completed. Closes time registration, completes open milestones, moves every open contract to Completed. Refused (37969) when a multi-customer contract uses the system customer. | | 5 | Archived | Archived. Closes time registration, completes open milestones, moves every open contract to Completed. | | 6 | Cancelled | Cancelled. Closes time registration, completes open milestones, moves every open contract to Cancelled. |

Format: int32 • Options: 0, 1, 2, 3, 4, 5, 6
Datestringnull

Status date to record (date part only). When omitted: the date already stored for that status, or today (ProjectStatusUnitRule). Date only — no time component. Default: the status's existing date, else today - projectsIds has exactly one character — Replaced by today's date. - Time part sent — statusDate.Value.Date keeps the date only.

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.

Query Parameters

projectsIdsstring
Required

Comma-separated project IDs, processed in order; duplicates are processed (and counted) twice. Omitted → 405 (captured). A non-integer entry → 500 after the entries before it were applied.

Several values: one string, separated by ,.

Body

application/json
Statusinteger

The new status, as the OrderStatus integer. Non-nullable: when omitted it arrives as 0 and is APPLIED — &#123;} moves every listed project to Quote.

  • Not one of 0–6 — 400 "Status must be 0 = Quote or 1 = Approved or 2 = InProgress or 3 = OnHold or 4 = Completed or 5 = Archived or 6 = Cancelled."

  • Omitted — 0 = Quote is applied.

  • Quote or Approved — OpenForTimeRegistration is left as the project had it (the controller passes the project's own flag).

Allowed values:

ValueNameMeaning
0QuoteQuote. Time registration keeps the project's current open/closed flag.
1ApprovedApproved. Time registration keeps the project's current open/closed flag.
2InProgressIn progress. Opens the project for time registration.
3OnHoldOn hold. Closes the project for time registration.
4CompletedCompleted. Closes time registration, completes open milestones, moves every open contract to Completed. Refused (37969) when a multi-customer contract uses the system customer.
5ArchivedArchived. Closes time registration, completes open milestones, moves every open contract to Completed.
6CancelledCancelled. Closes time registration, completes open milestones, moves every open contract to Cancelled.
Allowed values:0123456
Datestring,null

Status date to record (date part only). When omitted: the date already stored for that status, or today (ProjectStatusUnitRule).

Date only — no time component.

Default: the status's existing date, else today

  • projectsIds has exactly one character — Replaced by today's date.

  • Time part sent — statusDate.Value.Date keeps the date only.

Responses

Propertiesobject

How many projects a /v2/projects bulk write processed or changed.

Linksarray
Actionsobject[]