Scope requirements
Scope requirements
What’s new in 2026-09-beta
In2026-09-beta 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-beta/{objectTypeId}/{pipelineId}DELETE/crm/pipelines/2026-09-beta/{objectTypeId}/{pipelineId}/stages/{stageId}PATCH/crm/pipelines/2026-09-beta/{objectTypeId}/{pipelineId}PUT/crm/pipelines/2026-09-beta/{objectTypeId}/{pipelineId}
Bypass reference validation checks
To bypass a validation check (i.e., allow a pipeline or stage to be deleted regardless of references), set thevalidateDealStageUsagesBeforeDelete (deal pipelines) or validateReferencesBeforeDelete (all other object pipelines) field to false in your request.
For example, to skip validation and delete a deal pipeline, include the validateDealStageUsagesBeforeDelete in your request: /crm/pipelines/2026-09-beta/0-3/sales_pipeline?validateDealStageUsagesBeforeDelete=false
Before migrating to /2026-09-beta/, 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.