Skip to main content
Last modified: November 4, 2025
In HubSpot, you can use the 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 HubSpot projects or developer projects.

​
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 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. 
{
  "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:
PropertyTypeDescription
hs_namestringThe name of the project.
hs_pipelinestringThe 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.
hs_pipeline_stagestringThe 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.
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. 
{
  "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:
PropertyTypeDescription
idstringThe project’s internal ID.
hs_namestringThe project’s name.
hs_descriptionstringThe project’s description.
hs_statusstringThe project’s status.
hs_typeenumerationThe project’s type. The following values are available by default but can be edited using the properties API or in your account: sales, marketing, service, internal_ops.
hs_target_due_datestringThe date the project is due, provided as a ISO 8601 timestamp.
hubspot_owner_idnumberThe 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: 
{
  "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.