# List Projects

List all projects by given filters.


# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Attendances API",
    "version": "2.0.0",
    "description": "Endpoints to manage attendance periods, projects and their members."
  },
  "servers": [
    {
      "url": "https://api.personio.de"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Projects",
      "description": "Endpoints relating to projects that can be associated with attendance periods."
    }
  ],
  "paths": {
    "/v2/projects": {
      "get": {
        "x-path-examples": {
          "200 LIST projects": {
            "value": "/papi/v2/projects"
          },
          "200 LIST projects by limit": {
            "value": "/papi/v2/projects",
            "query": "limit=1"
          },
          "200 LIST projects by id": {
            "value": "/papi/v2/projects",
            "query": "id=82173"
          },
          "200 LIST projects by multiple ids": {
            "value": "/papi/v2/projects",
            "query": "id=82173,82174"
          },
          "200 LIST projects by name": {
            "value": "/papi/v2/projects",
            "query": "name=Project Name"
          },
          "200 LIST projects by multiple names": {
            "value": "/papi/v2/projects",
            "query": "name=Project Name,Project Name 2"
          },
          "200 LIST projects by status": {
            "value": "/papi/v2/projects",
            "query": "status=ACTIVE"
          },
          "200 LIST projects by project code": {
            "value": "/papi/v2/projects",
            "query": "project_code=PRJ-1234"
          },
          "200 LIST projects by multiple project codes": {
            "value": "/papi/v2/projects",
            "query": "project_code=PRJ-1234,PRJ-5678"
          },
          "200 LIST projects by parent project id": {
            "value": "/papi/v2/projects",
            "query": "parent_project.id=123"
          },
          "200 LIST projects by multiple parent project ids": {
            "value": "/papi/v2/projects",
            "query": "parent_project.id=123,456"
          },
          "200 LIST projects with included fields": {
            "value": "/papi/v2/projects",
            "query": "include=tracked_minutes,sub_projects_tracked_minutes,sub_projects_count,tracked_periods_count"
          },
          "200 LIST projects by top level only": {
            "value": "/papi/v2/projects",
            "query": "top_level_only=true"
          },
          "422 Invalid include parameter": {
            "value": "/papi/v2/projects",
            "query": "include=invalid_field"
          },
          "422 Invalid limit": {
            "value": "/papi/v2/projects",
            "query": "limit=300"
          },
          "422 Invalid status": {
            "value": "/papi/v2/projects",
            "query": "status=notvalid"
          },
          "403 Forbidden response": {
            "value": "/papi/v2/projects"
          }
        },
        "tags": [
          "Projects"
        ],
        "summary": "List Projects",
        "description": "List all projects by given filters.\n",
        "parameters": [
          {
            "in": "query",
            "name": "cursor",
            "example": "cur_82sQwR2eZvKilo2duNh219Kw",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The pagination cursor to navigate over to the next list of resources. If you pass a specific limit to your  request, or you rely on the default value of the number of resources to be returned, then your subsequent call has to include the cursor in order to retrieve the next list of resources. If cursor is missing,  the first page is returned."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 200
            },
            "description": "The maximum number of projects returned per request."
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "description": "Filter results matching any of the provided projects' ids.\n"
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "description": "Filter results matching any of the provided project names. Multiple names should be comma-separated.\n"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "ACTIVE",
                "ARCHIVED"
              ]
            },
            "description": "The status of the projects to filter by."
          },
          {
            "name": "project_code",
            "in": "query",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "description": "Filter results matching any of the provided project codes. Multiple codes should be comma-separated.\n"
          },
          {
            "name": "parent_project.id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "description": "Filter results matching any of the provided parent project ids. Multiple ids should be comma-separated.\n"
          },
          {
            "name": "top_level_only",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "Filter results to only include top level projects (Projects without a parent project).\n"
          },
          {
            "name": "include",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "tracked_minutes",
                  "sub_projects_tracked_minutes",
                  "sub_projects_count",
                  "tracked_periods_count"
                ]
              }
            },
            "description": "Include additional information in the response. Multiple values should be comma-separated.\nThese fields are not included by default for performance reasons.\n"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/ListProjectsResponse"
          },
          "403": {
            "$ref": "#/components/responses/ForbiddenResponse"
          },
          "422": {
            "$ref": "#/components/responses/ListProjectsBadRequestResponse"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "Project": {
        "type": "object",
        "description": "- Model of project entity. - Describes a project that can be associated with an attendance period.",
        "properties": {
          "id": {
            "type": "string",
            "example": "1234"
          },
          "name": {
            "description": "Name of the project.",
            "type": "string",
            "maxLength": 255,
            "example": "Project Name"
          },
          "status": {
            "description": "Status of the project.",
            "type": "string",
            "enum": [
              "ACTIVE",
              "ARCHIVED"
            ],
            "example": "ACTIVE"
          },
          "project_code": {
            "description": "Optional project code. This field needs to be unique across all projects (regardless of top level or sub project). It can be used as a reference to the projects in another system.\n",
            "type": "string",
            "nullable": true,
            "example": "PRJ-1234"
          },
          "description": {
            "description": "Optional project description.",
            "type": "string",
            "nullable": true,
            "maxLength": 1000,
            "example": "Project description"
          },
          "cost_center": {
            "description": "Optional cost center ID pointing to an existing Personio cost center ID.",
            "type": "object",
            "nullable": true,
            "required": [
              "id"
            ],
            "properties": {
              "id": {
                "type": "string",
                "example": "1234"
              }
            }
          },
          "assigned_to_all": {
            "description": "Flag to assign the project to all employees. Projects assigned to all employees can't have members. If set to true, every employee in the company is able to track time against this project. If set to false, only members of the project can track time against this project.\n",
            "type": "boolean",
            "example": false
          },
          "parent_project": {
            "description": "Optional parent project reference by Personio project ID. Sub projects can't be the parent of another sub project (at most one level of nesting).\n",
            "type": "object",
            "nullable": true,
            "required": [
              "id"
            ],
            "properties": {
              "id": {
                "type": "string",
                "example": "1234"
              }
            }
          },
          "start": {
            "description": "An optional start date of the project (inclusive).",
            "type": "object",
            "nullable": true,
            "required": [
              "date"
            ],
            "properties": {
              "date": {
                "type": "string",
                "format": "date",
                "example": "2022-01-01"
              }
            }
          },
          "end": {
            "description": "An optional end date of the project (exclusive).",
            "type": "object",
            "nullable": true,
            "required": [
              "date"
            ],
            "properties": {
              "date": {
                "type": "string",
                "format": "date",
                "example": "2022-01-01"
              }
            }
          },
          "billable": {
            "description": "Flag to mark project as billable.",
            "type": "boolean",
            "example": true
          },
          "client_name": {
            "description": "Optional client name for the project.",
            "type": "string",
            "nullable": true,
            "maxLength": 255,
            "example": "ACME Inc."
          },
          "project_type": {
            "description": "Optional project type. This is a free text field defined by the customer.\n",
            "type": "string",
            "nullable": true,
            "maxLength": 255,
            "example": "External"
          },
          "created_at": {
            "description": "Date and time when the project was created.",
            "type": "string",
            "format": "date-time",
            "example": "2022-01-01T14:00:00Z"
          },
          "updated_at": {
            "description": "Date and time when the project was last updated.",
            "type": "string",
            "format": "date-time",
            "example": "2022-01-01T14:00:00Z"
          },
          "tracked_minutes": {
            "description": "Total tracked minutes for the project and its subprojects. Rejected periods are not included. This field is only set when explicitly requested in the `include` parameter.\n",
            "type": "integer",
            "nullable": true,
            "example": 120
          },
          "sub_projects_tracked_minutes": {
            "description": "Total tracked minutes for the project's subprojects. Rejected periods are not included. This field is only set when explicitly requested in the `include` parameter.\n",
            "type": "integer",
            "nullable": true,
            "example": 60
          },
          "sub_projects_count": {
            "description": "Number of subprojects. This field is only set when explicitly requested in the `include` parameter.\n",
            "type": "integer",
            "nullable": true,
            "example": 1
          },
          "tracked_periods_count": {
            "description": "Number of tracked periods for the project and its subprojects. Attendance periods are counted even if they are rejected. This field is only set when explicitly requested in the `include` parameter.\n",
            "type": "integer",
            "nullable": true,
            "example": 2
          }
        }
      }
    },
    "responses": {
      "ForbiddenResponse": {
        "description": "Forbidden",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/responses/NotFoundResponse/content/application~1problem%2Bjson/schema"
            },
            "examples": {
              "403 Forbidden response": {
                "$ref": "#/components/examples/ForbiddenResponse"
              }
            }
          }
        }
      },
      "NotFoundResponse": {
        "description": "The resource could not be found.",
        "content": {
          "application/problem+json": {
            "schema": {
              "type": "object",
              "description": "This object represents an error response.",
              "properties": {
                "personio_trace_id": {
                  "type": "string",
                  "example": "aswo3f-a202lfso-312123sld-1230ddd",
                  "description": "A unique ID that was created for this error."
                },
                "timestamp": {
                  "type": "string",
                  "format": "date-time",
                  "example": "2021-05-28T11:17:30.000Z",
                  "description": "The timestamp of when the error occurred."
                },
                "errors": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "title": {
                        "type": "string",
                        "example": "Not found",
                        "description": "The title of the error."
                      },
                      "detail": {
                        "type": "string",
                        "example": "The requested resource was not found.",
                        "description": "A short description about the error."
                      },
                      "type": {
                        "type": "string",
                        "format": "uri",
                        "example": "https://developer.personio.de/reference/errors#common.requested_resource_not_found",
                        "description": "A link to the developer hub where more information can be found for the encountered error."
                      },
                      "_meta": {
                        "type": "object",
                        "additionalProperties": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            },
            "examples": {
              "404 Resource Not Found": {
                "$ref": "#/components/examples/NotFoundResponse"
              }
            }
          }
        }
      },
      "ListProjectsResponse": {
        "description": "Successful response.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "_data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Project"
                  }
                },
                "_meta": {
                  "description": "This object represents the metadata information for an object. It's a set of arbitrary key/value attributes such as `links`.",
                  "type": "object",
                  "readOnly": true,
                  "properties": {
                    "links": {
                      "type": "object",
                      "additionalProperties": {
                        "description": "This objects represents a hyperlink.",
                        "type": "object",
                        "readOnly": true,
                        "properties": {
                          "href": {
                            "type": "string",
                            "format": "uri"
                          }
                        },
                        "additionalProperties": true
                      },
                      "example": {
                        "links": {
                          "self": {
                            "href": "https://api.personio.de/v2/person?cursor=<current-cursor>"
                          }
                        }
                      }
                    }
                  }
                }
              }
            },
            "examples": {
              "200 LIST projects": {
                "$ref": "#/components/examples/ListProjectsResponseMultiItems"
              },
              "200 LIST projects by limit": {
                "$ref": "#/components/examples/ListProjectsResponseSingleItem"
              },
              "200 LIST projects by id": {
                "$ref": "#/components/examples/ListProjectsResponseSingleItem"
              },
              "200 LIST projects by multiple ids": {
                "$ref": "#/components/examples/ListProjectsResponseMultiItems"
              },
              "200 LIST projects by name": {
                "$ref": "#/components/examples/ListProjectsResponseSingleItem"
              },
              "200 LIST projects by multiple names": {
                "$ref": "#/components/examples/ListProjectsResponseMultiItems"
              },
              "200 LIST projects by status": {
                "$ref": "#/components/examples/ListProjectsResponseSingleItem"
              },
              "200 LIST projects by project code": {
                "$ref": "#/components/examples/ListProjectsResponseSingleItem"
              },
              "200 LIST projects by multiple project codes": {
                "$ref": "#/components/examples/ListProjectsResponseMultiItems"
              },
              "200 LIST projects by parent project id": {
                "$ref": "#/components/examples/ListProjectsResponseSingleItem"
              },
              "200 LIST projects by multiple parent project ids": {
                "$ref": "#/components/examples/ListProjectsResponseMultiItems"
              },
              "200 LIST projects by top level only": {
                "$ref": "#/components/examples/ListProjectsByTopLevelOnly"
              },
              "200 LIST projects with included fields": {
                "$ref": "#/components/examples/ListProjectsResponseWithInclude"
              }
            }
          }
        }
      },
      "ListProjectsBadRequestResponse": {
        "description": "Invalid request",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/responses/NotFoundResponse/content/application~1problem%2Bjson/schema"
            },
            "examples": {
              "422 Invalid include parameter": {
                "$ref": "#/components/examples/InvalidListIncludeResponse"
              },
              "422 Invalid limit": {
                "$ref": "#/components/examples/InvalidListLimitResponse"
              },
              "422 Invalid status": {
                "$ref": "#/components/examples/InvalidListProjectStatusResponse"
              }
            }
          }
        }
      }
    },
    "examples": {
      "ForbiddenResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30+00:00",
          "errors": [
            {
              "title": "Access denied",
              "detail": "Access denied to perform attendance period operations.",
              "type": "https://developer.personio.de/reference/errors#common.forbidden_response"
            }
          ]
        }
      },
      "InvalidListIncludeResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "Invalid include parameter.",
              "detail": "The provided value for the 'include' parameter is invalid. Please ensure that the value is one of: [tracked_minutes, sub_projects_tracked_minutes, sub_projects_count, tracked_periods_count]."
            }
          ]
        }
      },
      "InvalidListLimitResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "Invalid limit parameter.",
              "detail": "The provided value for the 'limit' parameter is invalid. Please ensure that the value is an integer within the range 1-200."
            }
          ]
        }
      },
      "ListProjectsResponseMultiItems": {
        "value": {
          "_data": [
            {
              "id": "82173",
              "name": "Project Name",
              "status": "ACTIVE",
              "project_code": "PRJ-1234",
              "description": "Project description",
              "cost_center": {
                "id": "1234"
              },
              "assigned_to_all": false,
              "parent_project": {
                "id": "123"
              },
              "start": {
                "date": "2024-01-01"
              },
              "end": {
                "date": "2025-01-01"
              },
              "billable": false,
              "client_name": "ACME Inc.",
              "project_type": "External",
              "created_at": "2022-01-01T14:00:00Z",
              "updated_at": "2022-01-01T14:00:00Z"
            },
            {
              "id": "82174",
              "name": "Project Name 2",
              "status": "ARCHIVED",
              "project_code": "PRJ-5678",
              "description": null,
              "cost_center": null,
              "assigned_to_all": false,
              "parent_project": {
                "id": "456"
              },
              "start": null,
              "end": null,
              "billable": false,
              "client_name": null,
              "project_type": null,
              "created_at": "2022-01-01T14:00:00Z",
              "updated_at": "2022-01-01T14:00:00Z"
            }
          ],
          "_meta": {
            "links": {
              "self": {
                "href": "https://api.personio.de/v2/projects"
              },
              "next": {
                "href": "https://api.personio.de/v2/projects?cursor=15sdwf2eIvLilN2dKFh211Js"
              }
            }
          }
        }
      },
      "ListProjectsResponseSingleItem": {
        "value": {
          "_data": [
            {
              "id": "82173",
              "name": "Project Name",
              "status": "ACTIVE",
              "project_code": "PRJ-1234",
              "description": "Project description",
              "cost_center": {
                "id": "1234"
              },
              "assigned_to_all": false,
              "parent_project": {
                "id": "123"
              },
              "start": {
                "date": "2024-01-01"
              },
              "end": {
                "date": "2025-01-01"
              },
              "billable": false,
              "client_name": "ACME Inc.",
              "project_type": "External",
              "created_at": "2022-01-01T14:00:00Z",
              "updated_at": "2022-01-01T14:00:00Z"
            }
          ],
          "_meta": {
            "links": {
              "self": {
                "href": "https://api.personio.de/v2/projects"
              },
              "next": {
                "href": "https://api.personio.de/v2/projects?cursor=15sdwf2eIvLilN2dKFh211Js"
              }
            }
          }
        }
      },
      "ListProjectsByTopLevelOnly": {
        "value": {
          "_data": [
            {
              "id": "82173",
              "name": "Project Name",
              "status": "ACTIVE",
              "project_code": null,
              "description": null,
              "cost_center": null,
              "assigned_to_all": false,
              "parent_project": null,
              "start": null,
              "end": null,
              "billable": false,
              "client_name": null,
              "project_type": null,
              "created_at": "2022-01-01T14:00:00Z",
              "updated_at": "2022-01-01T14:00:00Z"
            }
          ],
          "_meta": {
            "links": {
              "self": {
                "href": "https://api.personio.de/v2/projects?top_level_only=true"
              },
              "next": {
                "href": "https://api.personio.de/v2/projects?cursor=15sdwf2eIvLilN2dKFh211Js"
              }
            }
          }
        }
      },
      "ListProjectsResponseWithInclude": {
        "value": {
          "_data": [
            {
              "id": "82173",
              "name": "Project Name",
              "status": "ACTIVE",
              "project_code": "PRJ-1234",
              "description": "Project description",
              "cost_center": {
                "id": "1234"
              },
              "assigned_to_all": false,
              "parent_project": {
                "id": "123"
              },
              "start": {
                "date": "2024-01-01"
              },
              "end": {
                "date": "2025-01-01"
              },
              "billable": false,
              "client_name": "ACME Inc.",
              "project_type": "External",
              "created_at": "2022-01-01T14:00:00Z",
              "updated_at": "2022-01-01T14:00:00Z",
              "tracked_minutes": 120,
              "sub_projects_tracked_minutes": 60,
              "sub_projects_count": 1,
              "tracked_periods_count": 2
            }
          ],
          "_meta": {
            "links": {
              "self": {
                "href": "https://api.personio.de/v2/projects?cursor=35yM9aE27fsB4Joth7iDGgyk"
              },
              "next": {
                "href": "https://api.personio.de/v2/projects?cursor=15sdwf2eIvLilN2dKFh211Js"
              }
            }
          }
        }
      },
      "InvalidListProjectStatusResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "Invalid status parameter.",
              "detail": "The provided value for the 'status' parameter is invalid. Please ensure that the value is one of: [ACTIVE, ARCHIVED]."
            }
          ]
        }
      }
    }
  }
}
```