> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
---
id: 34a5f9db-77cc-4898-9b59-0a58270a01de
---
# Projects API
> Projects help you plan and organize your team's work in one place with structured lists of tasks. Learn how to use the projects endpoints to get project data from your account.
export const PostmanCard = ({title, collectionId}) => {
return ;
};
In HubSpot, you can use the [projects object](https://knowledge.hubspot.com/records/understand-and-use-projects-object) to help you manage your team's work in one place. You can then use the projects API to programmatically retrieve and manage projects in your account.
This guide refers to the projects object, not [developer projects](/developer-tooling/local-development/hubspot-cli/project-commands).
## Scope requirements
To use the projects API, you'll need to authorize one of the following scopes for your app, based on the functionality you plan on using:
* `crm.objects.projects.read`: Retrieve project data.
* `crm.objects.projects.write`: Create, manage, and delete projects.
* `crm.schemas.projects.read`: Retrieve property settings for your projects.
* `crm.schemas.projects.write`: Update property settings for projects.
To view or manage [Sensitive Data and Highly Sensitive data](/api-reference/latest/crm/properties/sensitive-data) for projects, you'd also need to authorize the following scopes:
* `crm.objects.projects.highly_sensitive.read`: View Highly Sensitive Data properties and values for projects.
* `crm.objects.projects.highly_sensitive.write`: Edit Highly Sensitive Data properties and values for projects.
* `crm.objects.projects.sensitive.read`: View Sensitive Data properties and values for projects.
* `crm.objects.projects.sensitive.write`: Edit Sensitive Data properties and values for projects.
## Create projects
To create a project, make a `POST` request to `/crm/v3/objects/projects`, and include any properties for the project as fields within the `properties` object of your request body.
For example, the following request body would create a new project with a name of *Sample Project*, along with providing the required project pipeline information.
```json theme={null}
{
"properties": {
"hs_name": "Sample Project",
"hs_pipeline": "acc364b5-d367-49f4-a957-cc4fbf7e8e4b",
"hs_pipeline_stage": "acc364b5-d367-49f4-a957-cc4fbf7e8e4b"
}
}
```
When creating a new project, the following properties are required:
| Property | Type | Description |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `hs_name` | string | The name of the project. |
| `hs_pipeline` | string | The internal ID of the project pipeline. You can find this ID by navigating to the project object settings page in your account, or by using the [pipelines API](/api-reference/latest/crm/pipelines/guide). |
| `hs_pipeline_stage` | string | The internal ID of the pipeline stage. You can find this ID by navigating to the project object settings page in your account, or by using the [pipelines API](/api-reference/latest/crm/pipelines/guide). |
You can also create multiple projects in bulk. To do this, make a `POST` request to `/crm/v3/objects/projects/batch/create`, and provide the data for each project within an `inputs` array in the body of your request.
For example, the following request body would create two different projects, including one that specifies an association with an existing task that has an ID of `27771003477`.
```json theme={null}
{
"inputs": [
{
"properties": {
"hs_name": "Project 1",
"hs_pipeline": "139663aa-09ee-418e-b67d-c8cfcd3e5ce3",
"hs_pipeline_stage": "c51bb66c-8141-44ef-82ec-703ae9c3a19f"
}
},
{
"properties": {
"hs_name": "Project 2",
"hs_pipeline": "139663aa-09ee-418e-b67d-c8cfcd3e5ce3",
"hs_pipeline_stage": "6480a063-31a5-4beb-bce8-12e2edb48f83"
},
"associations": [
{
"to": {
"id": 27771003477
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 1246
}
]
}
]
}
]
}
```
## Retrieve project data
To retrieve existing projects, make a `GET` request to `/crm/v3/objects/projects`. To limit the entries returned in the response, you can include the `limit` query parameter in your request (e.g., ?limit=5 would return up to five projects). You can also retrieve a specific project using its ID by making a `GET` request to `/crm/v3/objects/projects/{id}`.
You can provide any properties you want to include in the response using the `?properties` query parameter. For example, making a `GET` request to `/crm/v3/objects/projects?properties=hs_name,hs_description` would include the name and description of each project in the response.
The table below provides some common project properties:
| Property | Type | Description |
| -------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | string | The project's internal ID. |
| `hs_name` | string | The project's name. |
| `hs_description` | string | The project's description. |
| `hs_status` | string | The project's status. |
| `hs_type` | enumeration | The project's type. The following values are available by default but can be edited using the [properties API](/api-reference/legacy/crm/properties/guide) or in [your account](https://knowledge.hubspot.com/properties/create-and-edit-properties): `sales`, `marketing`, `service`, `internal_ops`. |
| `hs_target_due_date` | string | The date the project is due, provided as a ISO 8601 timestamp. |
| `hubspot_owner_id` | number | The ID of the HubSpot user. |
## Update project data
To update an existing project, make a `PATCH` request to `/crm/v3/objects/projects/{projectId}` using the project's ID as the `projectId` path parameter, and include the data you want to update within the `properties` object of the request body.
For example, if you wanted to update the project name, the request body would resemble the following:
```json theme={null}
{
"properties": {
"hs_name": "New title"
}
}
```
## Delete projects
To delete an existing project, make a `DELETE` request to `/crm/v3/objects/projects/{projectId}` using the project's ID as the `projectId` path parameter. If successful, the response will be `204 No Content`.