Required Scopes
Required Scopes
What’s new in 2026-09
In2026-09 and future versions of the Pipelines API, HubSpot will validate references before deleting a pipeline or pipeline stage. If a pipeline or stage is in use (e.g., the pipeline has records, or is referenced by a workflow), the delete request will be blocked and return a validation error.
To validate, in requests to the following endpoints, the validateDealStageUsagesBeforeDelete (deal pipelines) or validateReferencesBeforeDelete (all other object pipelines) field defaults to true.
DELETE/crm/pipelines/2026-09/{objectTypeId}/{pipelineId}DELETE/crm/pipelines/2026-09/{objectTypeId}/{pipelineId}/stages/{stageId}PATCH/crm/pipelines/2026-09/{objectTypeId}/{pipelineId}PUT/crm/pipelines/2026-09/{objectTypeId}/{pipelineId}
validateDealStageUsagesBeforeDelete (deal pipelines) or validateReferencesBeforeDelete (all other object pipelines) parameter to false in your request.
For example, to skip validation and delete a deal pipeline, include the validateDealStageUsagesBeforeDelete query parameter in your request: /crm/pipelines/2026-09/0-3/sales_pipeline?validateDealStageUsagesBeforeDelete=false
Before migrating to /2026-09/, review integration logic that deletes pipelines or pipeline stages.
- If deletes are expected to succeed even when a pipeline or stage is in use, update the requests to pass
falseto the validation query parameters. - If deletes should not succeed when pipelines or stages are in use, no changes are needed. Users will need to remove references to the pipeline or stages before retrying the delete request.
Manage pipelines
Create a pipeline
To create a new pipeline, make aPOST request to /crm/pipelines/2026-09/{objectType}. In the request body, include the following:
For each stage input, include the following fields:
For example, to create a new deal pipeline, your request may look like the following:
Replace a pipeline
If there’s an existing pipeline you want to replace instead of creating a new pipeline, make aPUT request to /crm/pipelines/2026-09/{objectType}/{pipelineId} with the id of the pipeline to replace. In the request body, include the fields required when creating a new pipeline. The information you include in the request body will overwrite the existing pipeline’s details. If you don’t want to fully overwrite the pipeline’s details, make a PATCH request instead.
Retrieve pipelines
- To retrieve all pipelines for an object, make a
GETrequest to/crm/pipelines/2026-09/{objectType}. Each pipeline’sid,label, anddisplayOrdervalues will be returned, along with information about when it was created or updated. You can use theidvalues to retrieve and update individual pipelines. - To retrieve an individual pipeline, make a
GETrequest to/crm/pipelines/2026-09/{objectType}/{pipelineId}.
Update a pipeline
To partially edit a pipeline’s details, such as label or display order, make aPATCH request to /crm/pipelines/2026-09/{objectType}/{pipelineId}. In the request body, include the properties to update. Other fields will not be overwritten.
If you want to edit a pipeline’s stages, use the stage endpoints.
Delete a pipeline
To delete a pipeline, make aDELETE request to /crm/pipelines/2026-09/{objectType}/{pipelineId}.
By default, the endpoint blocks deletes if the pipeline includes records or has references in other tools. If there are existing records, your response will look similar to the following:
validateDealStageUsagesBeforeDelete (deal pipelines) or validateReferencesBeforeDelete (all other object pipelines) parameter to false in your request.
Manage pipeline stages
Create a stage
To add a new stage to a pipeline, make aPOST request to /crm/pipelines/2026-09/{objectType}/{pipelineId}/stages.
In the request body, include the following:
For example, to add a stage called Contract signed as the fifth stage in a pipeline, your request would look like:
Replace a stage
To replace a stage’s details, make aPUT request to /crm/pipelines/2026-09/{objectType}/{pipelineId}/stages/{stageId}. Include the required fields in your request body. This request will overwrite the stage’s existing details.
If you don’t want to fully overwrite the stage’s details (i.e. change one field), make a PATCH request instead.
Retrieve stages
- To retrieve all stages in a pipeline, make a
GETrequest to/crm/pipelines/2026-09/{objectType}/{pipelineId}/stages. Each stage’sid,label, anddisplayOrdervalues will be returned, along with information about when it was created or updated. You can use theidvalues to retrieve and update individual stages. - To retrieve an individual stage, make a
GETrequest to/crm/pipelines/2026-09/{objectType}/{pipelineId}/stages/{stageId}.
Update a stage
To partially edit a stage’s details, such as label or display order, make aPATCH request to /crm/pipelines/2026-09/{objectType}/{pipelineId}/stages/{stageId}. In the request body, include the properties to update. Other fields will not be overwritten.
Delete a stage
To delete a pipeline stage, make aDELETE request to /crm/pipelines/2026-09/{objectType}/{pipelineId}/stages/{stageId}.
By default, the endpoint blocks deletes if the stage includes records or has references in other tools. To bypass the validation check (i.e., allow a stage to be deleted regardless of references), set the validateDealStageUsagesBeforeDelete (deal pipelines) or validateReferencesBeforeDelete (all other object pipelines) parameter to false in your request.
Track changes to pipelines and stages
You can use the audit endpoints to track changes made to your pipelines and pipeline stages.- To view changes made to a pipeline, make a
GETrequest to/crm/pipelines/2026-09/{objectType}/{pipelineId}/audit. - To view changes made to a stage, make a
GETrequest to/crm/pipelines/2026-09/{objectType}/{pipelineId}/stages/{stageId}/audit.