# Create a project.

Create a project and return the newly created project ID.

# 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": {
      "post": {
        "x-path-examples": {
          "201 POST Project valid request": {
            "value": "/papi/v2/projects"
          },
          "400 Invalid Project JSON": {
            "value": "/papi/v2/projects"
          },
          "400 Invalid Project status field": {
            "value": "/papi/v2/projects"
          },
          "400 Missing Project required parameters": {
            "value": "/papi/v2/projects"
          },
          "403 Forbidden response": {
            "value": "/papi/v2/projects"
          },
          "422 Duplicate Project Name": {
            "value": "/papi/v2/projects"
          },
          "422 Duplicate Project Code": {
            "value": "/papi/v2/projects"
          },
          "422 Cost Center does not exist": {
            "value": "/papi/v2/projects"
          },
          "422 Parent Project does not exist": {
            "value": "/papi/v2/projects"
          },
          "422 Start date greater than end date": {
            "value": "/papi/v2/projects"
          },
          "422 Unsupported field set for subproject": {
            "value": "/papi/v2/projects"
          }
        },
        "tags": [
          "Projects"
        ],
        "summary": "Create a project.",
        "description": "Create a project and return the newly created project ID.",
        "requestBody": {
          "$ref": "#/components/requestBodies/CreateProjectRequest"
        },
        "responses": {
          "201": {
            "$ref": "#/components/responses/ProjectCreatedResponse"
          },
          "400": {
            "$ref": "#/components/responses/ProjectBadRequestErrorResponse"
          },
          "403": {
            "$ref": "#/components/responses/ForbiddenResponse"
          },
          "422": {
            "$ref": "#/components/responses/ProjectUnprocessableContentErrorResponse"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "requestBodies": {
      "CreateProjectRequest": {
        "description": "Request object for creating a new project.",
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "name",
                "status"
              ],
              "properties": {
                "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",
                  "maxLength": 1000,
                  "example": "Project description"
                },
                "cost_center": {
                  "description": "Optional cost center ID pointing to an existing Personio cost center ID.\nSub projects (projects with a parent project) can't have a cost center.\n",
                  "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.\nIf not provided, the default value is false.\nSub projects (projects with a parent project) always have the same assigment as their parent project. This field shouldn't be provided for sub projects.\n",
                  "type": "boolean",
                  "nullable": true,
                  "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.\nIf not provided, the default value is false.\nSub projects (projects with a parent project) always have the same billable flag as their parent project. This field shouldn't be provided for sub projects.\n",
                  "type": "boolean",
                  "nullable": true,
                  "example": true
                },
                "client_name": {
                  "description": "Optional client name for the project.\nSub projects (projects with a parent project) can't have a client name.\n",
                  "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. Sub projects (projects with a parent project) can't have a project type.\n",
                  "type": "string",
                  "nullable": true,
                  "maxLength": 255,
                  "example": "External"
                }
              }
            },
            "examples": {
              "201 POST Project valid request": {
                "value": {
                  "name": "Project Name",
                  "status": "ACTIVE",
                  "project_code": "PRJ-1234",
                  "description": "Project description",
                  "cost_center": {
                    "id": "1234"
                  },
                  "assigned_to_all": false,
                  "parent_project": {
                    "id": "1234"
                  },
                  "start": {
                    "date": "2022-01-01"
                  },
                  "end": {
                    "date": "2022-01-01"
                  },
                  "billable": false,
                  "client_name": "ACME Inc.",
                  "project_type": "External"
                }
              },
              "400 Invalid Project JSON": {
                "value": {
                  "random": "INVALID JSON"
                }
              },
              "400 Invalid Project status field": {
                "value": {
                  "name": "Project Name",
                  "status": "INVALID"
                }
              },
              "400 Missing Project required parameters": {
                "value": {
                  "name": "Project Name"
                }
              },
              "403 Forbidden response": {
                "value": {
                  "name": "Project Name",
                  "status": "ACTIVE"
                }
              },
              "422 Duplicate Project Name": {
                "value": {
                  "name": "Project Name",
                  "status": "ACTIVE"
                }
              },
              "422 Duplicate Project Code": {
                "value": {
                  "name": "Project Name",
                  "status": "ACTIVE",
                  "project_code": "PRJ-1234"
                }
              },
              "422 Cost Center does not exist": {
                "value": {
                  "name": "Project Name",
                  "status": "ACTIVE",
                  "cost_center": {
                    "id": "1234"
                  }
                }
              },
              "422 Parent Project does not exist": {
                "value": {
                  "name": "Project Name",
                  "status": "ACTIVE",
                  "parent_project": {
                    "id": "1234"
                  }
                }
              },
              "422 Start date greater than end date": {
                "value": {
                  "name": "Project Name",
                  "status": "ACTIVE",
                  "start": {
                    "date": "2022-01-01"
                  },
                  "end": {
                    "date": "2021-01-01"
                  }
                }
              },
              "422 Unsupported field set for subproject": {
                "value": {
                  "name": "Project Name",
                  "status": "ACTIVE",
                  "project_code": "PRJ-1234",
                  "parent_project": {
                    "id": "1234"
                  }
                }
              }
            }
          }
        }
      }
    },
    "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"
              }
            }
          }
        }
      },
      "ProjectCreatedResponse": {
        "description": "Successful response.",
        "content": {
          "application/json": {
            "schema": {
              "description": "This is an object that is returned whenever a new resource is created. It contains the unique identifier for the created resource and optionally a link that can be used to retrieve it.",
              "properties": {
                "id": {
                  "readOnly": true,
                  "type": "string",
                  "example": "some-random-id",
                  "description": "The id of the created resource."
                },
                "_meta": {
                  "$ref": "#/components/responses/ListProjectsResponse/content/application~1json/schema/properties/_meta"
                }
              }
            },
            "examples": {
              "201 POST Project valid request": {
                "$ref": "#/components/examples/PostProjectResponse"
              }
            }
          }
        }
      },
      "ProjectBadRequestErrorResponse": {
        "description": "Invalid request.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/responses/NotFoundResponse/content/application~1problem%2Bjson/schema"
            },
            "examples": {
              "400 Invalid Project JSON": {
                "$ref": "#/components/examples/InvalidPostPayloadResponse"
              },
              "400 Invalid Project status field": {
                "$ref": "#/components/examples/InvalidProjectStatusPayloadResponse"
              },
              "400 Missing Project required parameters": {
                "$ref": "#/components/examples/MissingProjectRequiredFieldsPayloadResponse"
              }
            }
          }
        }
      },
      "ProjectUnprocessableContentErrorResponse": {
        "description": "Unprocessable content.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/responses/NotFoundResponse/content/application~1problem%2Bjson/schema"
            },
            "examples": {
              "422 Duplicate Project Name": {
                "$ref": "#/components/examples/DuplicateProjectNameResponse"
              },
              "422 Duplicate Project Code": {
                "$ref": "#/components/examples/DuplicateProjectCodeResponse"
              },
              "422 Cost Center does not exist": {
                "$ref": "#/components/examples/CostCenterDoesNotExistResponse"
              },
              "422 Parent Project does not exist": {
                "$ref": "#/components/examples/ParentProjectDoesNotExistResponse"
              },
              "422 Start date greater than end date": {
                "$ref": "#/components/examples/ProjectStartGreaterThanEndResponse"
              },
              "422 Unsupported field set for subproject": {
                "$ref": "#/components/examples/UnsupportedFieldSetForSubprojectResponse"
              }
            }
          }
        }
      }
    },
    "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"
            }
          ]
        }
      },
      "InvalidPostPayloadResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "Input must be valid JSON",
              "detail": "The provided input is not a JSON object."
            }
          ]
        }
      },
      "InvalidProjectStatusPayloadResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "Invalid field value",
              "detail": "Invalid value for field: status. Supported values are [ACTIVE, ARCHIVED]"
            }
          ]
        }
      },
      "MissingProjectRequiredFieldsPayloadResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30+00:00",
          "errors": [
            {
              "title": "Missing required fields",
              "detail": "The following required fields are missing: [status]",
              "_meta": {
                "field": "status"
              }
            }
          ]
        }
      },
      "PostProjectResponse": {
        "value": {
          "id": "1234"
        }
      },
      "DuplicateProjectNameResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "Duplicate project name.",
              "detail": "A project with the name 'Project Name' already exists. Please choose a different name."
            }
          ]
        }
      },
      "DuplicateProjectCodeResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "Duplicate project code.",
              "detail": "A project with the code 'PRJ-1234' already exists. Please choose a different code."
            }
          ]
        }
      },
      "CostCenterDoesNotExistResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "Cost center does not exist.",
              "detail": "The provided cost center ID does not exist. Please ensure that the cost center ID is correct."
            }
          ]
        }
      },
      "ParentProjectDoesNotExistResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "Parent project does not exist.",
              "detail": "The provided parent project ID does not exist. Please ensure that the parent project ID is correct."
            }
          ]
        }
      },
      "ProjectStartGreaterThanEndResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "Invalid start date",
              "detail": "Project start date cannot be greater than end date."
            }
          ]
        }
      },
      "UnsupportedFieldSetForSubprojectResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "Unsupported field set for subproject.",
              "detail": "The following fields should not be set for a subproject: [cost_center, assigned_to_all, project_type, client_name, billable]"
            }
          ]
        }
      }
    }
  }
}
```