GET/projects/api/v3/projects.json

Returns a list of projects - V3

Retrieve all projects for the provided filters. Only the projects that the logged-in user can access will be returned.

On this endpoint you can filter by project custom fields. The syntax for the query parameter is the following:

projectCustomField[id][op]=value

Where:

  • [id] is the custom field ID
  • [op] is the operator to apply when filtering, different operators are allowed according to the custom field type
  • [value] is the value to apply when filtering

For example, if I want to filter a dropdown custom field with ID 10 to only return entries that have the value "Option1" we would do the following:

projectCustomField[10][eq]=Option1

The allowed operators are:

  • like
  • not-like
  • eq
  • not
  • lt
  • gt
  • any

The like and not-like operators use the %25 wildcard character. ie: To filter a dropdown custom field with ID 10 to return entries that contain the value "ption" we would do the following

projectCustomField[10][like]=%25ption%25

Query Params

  • Name
    updatedAfter
    Type
    string
    Description

    updated after
    (Format: yyyy-mm-dd or yyyy-mm-ddThh:mm:ssZ)

    Default
    2024-06-21
  • Name
    searchTerm
    Type
    string
    Description

    filter by project name

    Default
    My first Project
  • Name
    reportType
    Type
    string
    Description

    define the type of the report

    Default
    project
    Allowed values
    • project
    • health
  • Name
    reportTimezone
    Type
    string
    Description

    Optional to configure the report dates displayed in a timezone

  • Name
    reportFormat
    Type
    string
    Description

    define the format of the report

    Default
    pdf
    Allowed values
    • csv
    • html
    • pdf
    • xls
  • Name
    projectType
    Type
    string
    Description

    filter by project type

  • Name
    orderMode
    Type
    string
    Description

    order mode

    Default
    asc
    Allowed values
    • asc
    • desc
  • Name
    orderBy
    Type
    string
    Description

    order by

    Default
    name
    Allowed values
    • companyname
    • datecreated
    • duedate
    • lastactivity
    • name
    • namecaseinsensitive
    • ownercompany
    • starred
    • categoryname
  • Name
    notCompletedBefore
    Type
    string
    Description

    filter by projects that have not been completed before the given date (Format: yyyy-mm-dd or yyyy-mm-ddThh:mm:ssZ)

  • Name
    minLastActivityDate
    Type
    string
    Description

    filter by min last activity date (Format: yyyy-mm-dd or yyyy-mm-ddThh:mm:ssZ)

  • Name
    maxLastActivityDate
    Type
    string
    Description

    filter by max last activity date (Format: yyyy-mm-dd or yyyy-mm-ddThh:mm:ssZ)

  • Name
    currencySymbol
    Type
    string
    Description

    currency symbol for report export

  • Name
    userId
    Type
    integer
    Description

    filter by user id

  • Name
    pageSize
    Type
    integer
    Description

    Number of items in a page (not used when generating reports) See How does paging work for more detailed documentation on pagination. Minimum: 1 Maximum: 500

    Default
    50
  • Name
    page
    Type
    integer
    Description

    Page number, this is usually used in conjunction with the parameter pageSize. (not used when generating reports) See How does paging work for more detailed documentation on pagination.

    Default
    1
  • Name
    orderByCustomFieldId
    Type
    integer
    Description

    order by custom field id when orderBy is equal to customfield

  • Name
    minBudgetCapacityUsedPercent
    Type
    integer
    Description

    filter by minimum budget capacity used

  • Name
    maxBudgetCapacityUsedPercent
    Type
    integer
    Description

    filter by maximum budget capacity used

  • Name
    useFormulaFields
    Type
    boolean
    Description

    use formula fields

    Default
    false
  • Name
    skipCounts
    Type
    boolean
    Description

    SkipCounts allows you to skip doing counts on a list API endpoint for performance reasons.

    Default
    false
  • Name
    searchCompanies
    Type
    boolean
    Description

    include companies in the search

    Default
    false
  • Name
    searchByLetter
    Type
    boolean
    Description

    search projects beginning with the search term character only when it contains a single character.

    Default
    false
  • Name
    onlyStarredProjects
    Type
    boolean
    Description

    filter by starred projects only

    Default
    false
  • Name
    onlyProjectsWithExplicitMembership
    Type
    boolean
    Description

    only show projects with explicit membership

    Default
    false
  • Name
    onlyProjectsThatCanLogTime
    Type
    boolean
    Description

    can log time on projects

    Default
    false
  • Name
    onlyArchivedProjects
    Type
    boolean
    Description

    return only archived projects

    Default
    false
  • Name
    matchAllProjectTags
    Type
    boolean
    Description

    match all project tags (used when filtering with tags)

    Default
    false
  • Name
    matchAllExcludedTags
    Type
    boolean
    Description

    match all excluded project tags (used when filtering with tags)

    Default
    false
  • Name
    isReportDownload
    Type
    boolean
    Description

    generate a report document

    Default
    false
  • Name
    includeTentativeProjects
    Type
    boolean
    Description

    include alongside normal projects, tentative ones

    Default
    false
  • Name
    includeSubCategories
    Type
    boolean
    Description

    include sub categories when filtering by ids

    Default
    false
  • Name
    includeStats
    Type
    boolean
    Description

    include project status counts for tasks columns billing events milestones

    Default
    false
  • Name
    includeProjectUserInfo
    Type
    boolean
    Description

    fetch user-specific data such as isStarred

    Default
    false
  • Name
    includeProjectProfitability
    Type
    boolean
    Description

    include project profitability in response

    Default
    false
  • Name
    includeProjectDates
    Type
    boolean
    Description

    include minimum and maximum start/end dates for projects

    Default
    false
  • Name
    includeCustomFields
    Type
    boolean
    Description

    include custom fields

    Default
    false
  • Name
    includeCounts
    Type
    boolean
    Description

    include project related counts

    Default
    false
  • Name
    includeCompletedStatus
    Type
    boolean
    Description

    optional to include completed projects when filtering by project statuses "current,late".

    Default
    false
  • Name
    includeArchivedProjects
    Type
    boolean
    Description

    include archived projects

    Default
    false
  • Name
    hideObservedProjects
    Type
    boolean
    Description

    hide projects where the logged-in user is just an observer

    Default
    false
  • Name
    alwaysIncludeFiltering
    Type
    boolean
    Description

    includes filters when project ids are provided

    Default
    false
  • Name
    teamIds
    Type
    array[integer]
    Description

    filter by projects that contain users associated with the team ids

    Format
    Comma separated values
  • Name
    selectedColumns
    Type
    array[string]
    Description

    select the columns to use in exports.

    Format
    Comma separated values
  • Name
    projectTagIds
    Type
    array[integer]
    Description

    filter by project tag ids

    Format
    Comma separated values
  • Name
    projectStatuses
    Type
    array[string]
    Description

    filter by project status

    Default
    active
    Format
    Comma separated values
    Allowed values
    • active
    • current
    • late
    • upcoming
    • completed
    • deleted
  • Name
    projectOwnerIds
    Type
    array[integer]
    Description

    filter by project owner ids

    Format
    Comma separated values
  • Name
    projectIds
    Type
    array[integer]
    Description

    filter by project ids

    Format
    Comma separated values
  • Name
    projectHealths
    Type
    array[integer]
    Description

    filter by project healths

    0: not set 1: bad 2: ok 3: good

    Format
    Comma separated values
    Allowed values
    • 0
    • 1
    • 2
    • 3
  • Name
    projectCompanyIds
    Type
    array[integer]
    Description

    filter by company ids

    Format
    Comma separated values
  • Name
    projectCategoryIds
    Type
    array[integer]
    Description

    filter by project category ids

    Format
    Comma separated values
  • Name
    includeCustomFieldIds
    Type
    array[integer]
    Description

    include specific custom fields

    Format
    Comma separated values
  • Name
    include
    Type
    array[string]
    Description

    include (not used when generating reports)

    Format
    Comma separated values
    Allowed values
    • projectOwners
    • projectUpdates
    • companies
    • companies.countries
    • companies.industries
    • projectCategories
    • portfolioCards
    • portfolioBoards
    • portfolioColumns
    • tags
    • customfields
    • customfieldProjects
    • projectBudgets
    • activities.latest
    • users
    • createdBy
    • updatedBy
    • completedBy
    • deletedBy
  • Name
    fields[workflows]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • name
    • statusId
  • Name
    fields[users]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • firstName
    • lastName
    • title
    • email
    • companyId
    • company
    • isAdmin
    • isClientUser
    • isServiceAccount
    • type
    • deleted
    • avatarUrl
    • lengthOfDay
    • workingHoursId
    • workingHour
    • userRate
    • userCost
    • canAddProjects
  • Name
    fields[tags]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • name
    • color
    • count
  • Name
    fields[stages]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • name
    • stage
  • Name
    fields[projects]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • name
  • Name
    fields[projectcategories]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • name
    • color
    • count
    • parent
    • parentId
  • Name
    fields[projectUpdates]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • projectId
    • text
    • isActive
    • health
    • color
    • dateCreated
    • deleted
    • deletedDate
    • numLikes
    • reactions
  • Name
    fields[projectBudgets]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • projectId
    • type
    • status
    • capacityUsed
    • capacity
    • originatorBudgetId
    • isRepeating
    • repeatPeriod
    • repeatUnit
    • repeatsRemaining
    • sequenceNumber
    • startDateTime
    • endDateTime
    • currencyCode
    • timelogType
    • expenseType
    • defaultRate
    • notificationIds
    • createdByUserId
    • dateCreated
    • updatedUserId
    • dateUpdated
    • completedByUserId
    • dateCompleted
    • deletedByUserId
    • dateDeleted
  • Name
    fields[portfolioColumns]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • name
    • color
  • Name
    fields[portfolioCards]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • columnId
    • projectId
  • Name
    fields[portfolioBoards]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • name
    • color
  • Name
    fields[industries]
    Type
    array[string]
    Description
    Format
    Comma separated values
  • Name
    fields[customfields]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • projectId
    • entity
    • name
    • description
    • type
    • options
    • visibilities
    • isPrivate
    • required
    • createdAt
    • createdByUserId
    • updatedAt
    • updatedByUserId
    • deleted
    • deletedAt
    • deletedByUserId
  • Name
    fields[customfieldProjects]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • customfieldId
    • value
    • createdAt
    • createdBy
  • Name
    fields[countries]
    Type
    array[string]
    Description
    Format
    Comma separated values
  • Name
    fields[companies]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • name
    • logoUploadedToServer
    • logoImage
  • Name
    featuresEnabled
    Type
    array[string]
    Description

    filter by projects that have features enabled

    Format
    Comma separated values
    Allowed values
    • list
    • board
    • gantt
    • table
    • dashboard
    • milestones
    • messages
    • files
    • time
    • notebooks
    • risks
    • links
    • billing
    • comments
    • people
    • settings
  • Name
    excludeTagIds
    Type
    array[integer]
    Description

    exclude by project tag ids

    Format
    Comma separated values

Responses

  • Code
    200
    Type
    object
    Schema
    Description
    200 OK
    projectsResponseV205 contains information about a group of projects.
  • Code
    400
    Type
    object
    Schema
    Description
    400 Bad Request
    ErrorResponse defines how []Error should be marshaled to JSON.
  • Code
    403
    Type
    object
    Schema
    Description
    403 Forbidden
    ErrorResponse defines how []Error should be marshaled to JSON.

Examples

200 OK

projectsResponseV205
{  "included": {    "activities": {      "additionalProp": {        "datetime": "string",        "description": "string",        "extraDescription": "string",        "id": 0,        "itemLink": "string",        "itemType": "string",        "latestType": "string",        "link": "string",        "user": {          "id": 0,          "meta": {},          "type": "string"        }      }
Download Swagger