ProjectsSearch projects by criteria

Search projects by criteria

Lists every non-template project the caller may see, filtered by up to 15 include/exclude ID lists and a text search, with hour aggregates.

Returns all matching non-template projects in ONE unpaged TAF list, ordered by project number then name, with list Properties: ProjectsCount, TotalBudgetWorkHours, TotalProjectActualHours, TotalTasksBudgetHours, TotalAllocationsBudgetHours (numbers as en-GB strings) and IsShowingProjectStage / IsShowingProjectCategory (account features, booleans). Every filter is an optional comma-separated ID list with an is…Inclusive switch (true = keep projects whose value is in the list, false = drop them); an empty list means no filter; filters AND together. searchText is a LIKE '%text%' over customer number and name, project number, name and description. A caller without project privileges gets an empty list.

Use it to:

  • Project overview / portfolio list with the same filters as the TimeLog project list
  • Find the projectId values to pass to the bulk status / stage / resource-planner / delete operations

Not for:

  • Paging through large accounts — there is no paging; use GET /v1/project/get-all
  • A project picker for time registration → GET /v1/project-header/search-for-time-tracking-order-by-recent-registration

Rules across fields:

  • R1: Each is…Inclusive switch is used only when its ID list is non-empty.

Behaviour:

  • Idempotent.
  • Safe to retry.
  • Changes are visible to the next read immediately.

Call first: GET /v2/filters/list/{pageIdentifier}

Next: GET /v2/projects/actions, GET /v2/projects/{projectId}/time-registrations

See also: GET /v1/project/get-all, GET /v2/filters/project-status/content

Not yet documented: request → query params → contractStatusIds; response → empty result.

curl -X GET "https://app3.timelog.com/your-account/api/v2/projects?searchText=example_string&customerIds=example_string&isCustomerInclusive=true&projectDepartmentIds=example_string&isProjectDepartmentInclusive=true&legalEntityProjectIds=example_string&isLegalEntityProjectInclusive=true&accountManagerIds=example_string&isAccountManagerInclusive=true&contractModelIds=example_string&isContractModelInclusive=true&contractStatusIds=example_string&isContractStatusInclusive=true&projectStatusIds=123&isProjectStatusInclusive=true&projectManagerIds=example_string&isProjectManagerInclusive=true&projectTypeIds=example_string&isProjectTypeInclusive=true&projectCategoryIds=example_string&isProjectCategoryInclusive=true&projectStageIds=example_string&isProjectStageInclusive=true&customerOwnerIds=example_string&isCustomerOwnerInclusive=true&contactIds=example_string&isContactInclusive=true&partnerIds=example_string&isPartnerInclusive=true&projectInactivityPeriodIds=example_string" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
{
  "Entities": [
    {
      "Properties": {
        "Id": "123e4567-e89b-12d3-a456-426614174000",
        "ProjectId": 123,
        "Name": "John Doe",
        "No": "example_string",
        "CustomerId": 123,
        "CustomerName": "John Doe",
        "CustomerOwnerId": 123,
        "LegalEntityId": 123,
        "ContactId": 123,
        "Description": "example_string",
        "DepartmentId": 123,
        "ProjectManagerId": 123,
        "ProjectManagerName": "John Doe",
        "ProjectManagerInitials": "example_string",
        "AccountManagerId": 123,
        "AccountManagerName": "John Doe",
        "AccountManagerInitials": "example_string",
        "PartnerId": 123,
        "ProjectTypeId": 123,
        "ProjectTypeName": "John Doe",
        "ProjectCategoryId": 123,
        "ProjectCategoryName": "John Doe",
        "ProjectStageId": 123,
        "ProjectStageName": "John Doe",
        "BudgetWorkHours": 3.14,
        "ProjectActualHours": 3.14,
        "TasksBudgetHours": 3.14,
        "AllocationsBudgetHours": 3.14,
        "StatusId": 123,
        "StatusName": "John Doe",
        "HasAccountingIssues": true,
        "Completion": 3.14,
        "ContractModels": [
          "null"
        ]
      },
      "Links": [
        {
          "Href": "example_string",
          "Rel": "example_string"
        }
      ],
      "Actions": [
        {}
      ]
    }
  ],
  "Links": [
    {
      "Href": "example_string",
      "Rel": "example_string"
    }
  ]
}
GET
/v2/projects
GET
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
searchTextstring

LIKE '%text%' on customer number, customer name, project number, project name and project description (OR). Wildcards % and _ are not escaped. Empty = no text filter. Filters on SearchProjectRead.No, Name, Description, CustomerName (+ customer number) (contains).

query
customerIdsstring

Customer IDs. Each entry must parse as an integer. Several values: one string, separated by ,.

query
isCustomerInclusiveboolean

true = only these customers; false = all but these. Filters on customerIds (in).

query
projectDepartmentIdsstring

Project (handling) department IDs, matched exactly (0 = projects without department); no subtree expansion. Several values: one string, separated by ,.

query
isProjectDepartmentInclusiveboolean

Include / exclude switch. Filters on projectDepartmentIds (in).

query
legalEntityProjectIdsstring

Project legal-entity IDs. Several values: one string, separated by ,.

query
isLegalEntityProjectInclusiveboolean

Include / exclude switch. Filters on legalEntityProjectIds (in).

query
accountManagerIdsstring

Account manager EMPLOYEE IDs. Several values: one string, separated by ,.

query
isAccountManagerInclusiveboolean

Include / exclude switch. Filters on accountManagerIds (in).

query
contractModelIdsstring

ContractModelType values. Matched per CONTRACT row: with isContractModelInclusive=false a project still matches when any other contract has another model. Several values: one string, separated by ,.

query
isContractModelInclusiveboolean

Include / exclude switch. Filters on contractModelIds (in).

query
contractStatusIdsstring

Contract status values; per contract row like contractModelIds. Several values: one string, separated by ,. Filters (in). Valid values come from GET /v2/filters/contract-status/content.

query
isContractStatusInclusiveboolean

Include / exclude switch. Filters on contractStatusIds (in).

query
projectStatusIdsinteger

PAGE-FILTER status codes, not StatusId: 1–7 map to StatusId 0–6 (1 = Quote … 7 = Cancelled); -1 = active group (Quote, Approved, InProgress, OnHold), -2 = inactive group (Completed, Archived, Cancelled), -3 = all. Any other integer passes through unchanged (so 0 also means Quote). When a group code is present the individual codes are ignored, and only one group applies: -3 over -2 over -1. Same codes as GET /v2/filters/project-status/content. Several values: one string, separated by ,. Filters on SearchProjectRead.StatusId (in). Allowed values: | Value | Name | Meaning | |---|---|---| | -3 | All | Every status 0–6. | | -2 | Inactive | Completed, Archived, Cancelled (4, 5, 6). | | -1 | Active | Quote, Approved, InProgress, OnHold (0–3). | | 1 | Quote | StatusId 0. | | 2 | Approved | StatusId 1. | | 3 | InProgress | StatusId 2. | | 4 | OnHold | StatusId 3. | | 5 | Completed | StatusId 4. | | 6 | Archived | StatusId 5. | | 7 | Cancelled | StatusId 6. |

Options: -3, -2, -1, 1, 2, 3, 4, 5, 6, 7
query
isProjectStatusInclusiveboolean

Include / exclude switch. Filters on projectStatusIds (in).

query
projectManagerIdsstring

Project manager EMPLOYEE IDs. Several values: one string, separated by ,.

query
isProjectManagerInclusiveboolean

Include / exclude switch. Filters on projectManagerIds (in).

query
projectTypeIdsstring

Project type IDs. Several values: one string, separated by ,.

query
isProjectTypeInclusiveboolean

Include / exclude switch. Filters on projectTypeIds (in).

query
projectCategoryIdsstring

Project category IDs. Several values: one string, separated by ,.

query
isProjectCategoryInclusiveboolean

Include / exclude switch. Filters on projectCategoryIds (in).

query
projectStageIdsstring

Project stage IDs (current stage). Projects without a stage never match an inclusive list and always survive an exclusive one. Several values: one string, separated by ,.

query
isProjectStageInclusiveboolean

Include / exclude switch. Filters on projectStageIds (in).

query
customerOwnerIdsstring

Customer-owner EMPLOYEE IDs. Not echoed in the response. Several values: one string, separated by ,. Filters (in). Valid values come from GET /v2/filters/customer-owner/content.

query
isCustomerOwnerInclusiveboolean

Include / exclude switch. Filters on customerOwnerIds (in).

query
contactIdsstring

Customer contact-person IDs. Several values: one string, separated by ,.

query
isContactInclusiveboolean

Include / exclude switch. Filters on contactIds (in).

query
partnerIdsstring

Partner IDs. Several values: one string, separated by ,.

query
isPartnerInclusiveboolean

Include / exclude switch. Filters on partnerIds (in).

query
projectInactivityPeriodIdsstring

ONE number of days N (despite the plural name): keep only projects whose newest registration LastModified — or, without registrations, whose creation — is older than N days. Parsed with TryParse: a list or a non-number silently means 0 = no filter. Filters on date of the latest time registration (or project creation when none) (lt). Valid values come from GET /v2/filters/project-inactivity-period/content.

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

searchTextstring

LIKE '%text%' on customer number, customer name, project number, project name and project description (OR). Wildcards % and _ are not escaped. Empty = no text filter.

Filters on SearchProjectRead.No, Name, Description, CustomerName (+ customer number) (contains).

customerIdsstring

Customer IDs. Each entry must parse as an integer.

Several values: one string, separated by ,.

isCustomerInclusiveboolean

true = only these customers; false = all but these.

Filters on customerIds (in).

projectDepartmentIdsstring

Project (handling) department IDs, matched exactly (0 = projects without department); no subtree expansion.

Several values: one string, separated by ,.

isProjectDepartmentInclusiveboolean

Include / exclude switch.

Filters on projectDepartmentIds (in).

legalEntityProjectIdsstring

Project legal-entity IDs.

Several values: one string, separated by ,.

isLegalEntityProjectInclusiveboolean

Include / exclude switch.

Filters on legalEntityProjectIds (in).

accountManagerIdsstring

Account manager EMPLOYEE IDs.

Several values: one string, separated by ,.

isAccountManagerInclusiveboolean

Include / exclude switch.

Filters on accountManagerIds (in).

contractModelIdsstring

ContractModelType values. Matched per CONTRACT row: with isContractModelInclusive=false a project still matches when any other contract has another model.

Several values: one string, separated by ,.

isContractModelInclusiveboolean

Include / exclude switch.

Filters on contractModelIds (in).

contractStatusIdsstring

Contract status values; per contract row like contractModelIds.

Several values: one string, separated by ,.

Filters (in).

Valid values come from GET /v2/filters/contract-status/content.

isContractStatusInclusiveboolean

Include / exclude switch.

Filters on contractStatusIds (in).

projectStatusIdsinteger

PAGE-FILTER status codes, not StatusId: 1–7 map to StatusId 0–6 (1 = Quote … 7 = Cancelled); -1 = active group (Quote, Approved, InProgress, OnHold), -2 = inactive group (Completed, Archived, Cancelled), -3 = all. Any other integer passes through unchanged (so 0 also means Quote). When a group code is present the individual codes are ignored, and only one group applies: -3 over -2 over -1. Same codes as GET /v2/filters/project-status/content.

Several values: one string, separated by ,.

Filters on SearchProjectRead.StatusId (in).

Allowed values:

ValueNameMeaning
-3AllEvery status 0–6.
-2InactiveCompleted, Archived, Cancelled (4, 5, 6).
-1ActiveQuote, Approved, InProgress, OnHold (0–3).
1QuoteStatusId 0.
2ApprovedStatusId 1.
3InProgressStatusId 2.
4OnHoldStatusId 3.
5CompletedStatusId 4.
6ArchivedStatusId 5.
7CancelledStatusId 6.
Allowed values:-3-2-11234567
isProjectStatusInclusiveboolean

Include / exclude switch.

Filters on projectStatusIds (in).

projectManagerIdsstring

Project manager EMPLOYEE IDs.

Several values: one string, separated by ,.

isProjectManagerInclusiveboolean

Include / exclude switch.

Filters on projectManagerIds (in).

projectTypeIdsstring

Project type IDs.

Several values: one string, separated by ,.

isProjectTypeInclusiveboolean

Include / exclude switch.

Filters on projectTypeIds (in).

projectCategoryIdsstring

Project category IDs.

Several values: one string, separated by ,.

isProjectCategoryInclusiveboolean

Include / exclude switch.

Filters on projectCategoryIds (in).

projectStageIdsstring

Project stage IDs (current stage). Projects without a stage never match an inclusive list and always survive an exclusive one.

Several values: one string, separated by ,.

isProjectStageInclusiveboolean

Include / exclude switch.

Filters on projectStageIds (in).

customerOwnerIdsstring

Customer-owner EMPLOYEE IDs. Not echoed in the response.

Several values: one string, separated by ,.

Filters (in).

Valid values come from GET /v2/filters/customer-owner/content.

isCustomerOwnerInclusiveboolean

Include / exclude switch.

Filters on customerOwnerIds (in).

contactIdsstring

Customer contact-person IDs.

Several values: one string, separated by ,.

isContactInclusiveboolean

Include / exclude switch.

Filters on contactIds (in).

partnerIdsstring

Partner IDs.

Several values: one string, separated by ,.

isPartnerInclusiveboolean

Include / exclude switch.

Filters on partnerIds (in).

projectInactivityPeriodIdsstring

ONE number of days N (despite the plural name): keep only projects whose newest registration LastModified — or, without registrations, whose creation — is older than N days. Parsed with TryParse: a list or a non-number silently means 0 = no filter.

Filters on date of the latest time registration (or project creation when none) (lt).

Valid values come from GET /v2/filters/project-inactivity-period/content.

Responses

Entitiesarray

Omitted (not []) when the list is empty.

Linksarray