Last modified: September 3, 2025
Run in Postman
- Deals
- Tickets
- Appointments
- Courses
- Listings
- Orders
- Services
- Leads (Sales Hub Professional and Enterprise only)
- Custom objects (Enterprise only)
Manage pipelines
Create a pipeline
Accounts with a Starter, Professional, or Enterprise subscription can create additional pipelines. If your account has a Sales Hub subscription, you can create multiple deal pipelines. If your account has a Service Hub subscription, you can create multiple ticket pipelines. To create a new pipeline, make aPOST request to /crm/v3/pipelines/{objectType}. In the request body, include the following:
displayOrder: a number that decides the order the pipeline is displayed within all pipelines of the object. If multiple pipelines are the same number in the order, they’ll be listed alphabetically by label.label: the name of the pipeline as it is displayed in HubSpot.stages: inputs to set the stages in the pipeline. For each stage, include the following:metadata: properties related to the stage, optional for all objects except deals. For deals,probabilityis required with a value between0.0and1.0,0.0being Closed Lost and1.0being Closed Won. For tickets, you can includeticketStatewith a value of eitherOPENorCLOSED.displayOrder: a number that decides the order in which the stage will be displayed.label: the stage name. This must be unique for each stage.
Please note:Appointment, course, listing, lead, order, and service pipelines can have up to 30 stages. Deal, ticket, and custom object pipelines can have up to 100 stages.
Replace a pipeline
If there’s an existing pipeline you want to replace instead of creating a new pipeline, make aPUT request to /crm/v3/pipelines/{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 add in the request body will overwrite the existing pipeline’s details.
Retrieve pipelines
- To retrieve all pipelines for an object, make a
GETrequest to/crm/v3/pipelines/{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/v3/pipelines/{objectType}/{pipelineId}.
Update a pipeline
To edit a pipeline’s details, such as label or display order, make aPATCH request to /crm/v3/pipelines/{objectType}/{pipelineId}. In the request body, include the properties to update.
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/v3/pipelines/{objectType}/{pipelineId}. To check if there are records in the pipeline, include the validateReferencesBeforeDelete parameter with a value of true. When the parameter is included, you’ll be notified of existing records and cannot delete the pipeline until the records have been deleted or moved to a different pipeline.
If there are existing records, your response will look similar to the following:
Manage pipeline stages
Create a stage
To add a new stage to a pipeline, make aPOST request to /crm/v3/pipelines/{objectType}/{pipelineId}/stages.
In the request body, include the following:
displayOrder: a number that decides the order of the stage in the pipeline. If multiple stages are the same number in the order, they’ll be listed alphabetically by label.label: the name of the stage as it is displayed in HubSpot.metadata: an object that includes properties for the stage, optional for all objects except deals. For deals,probabilityis required with a value between0.0and1.0,0.0being Closed Lost and1.0being Closed Won. For tickets, you can includeticketStatewith a value ofOPENorCLOSED.
Please note:Appointment, course, listing, lead, order, and service pipelines can have up to 30 stages. Deal, ticket, and custom object pipelines can have up to 100 stages.
Replace a stage
If there’s an existing pipeline stage you want to replace instead of creating a new stage, make aPUT request to /crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId} with the id of the stage to replace. In the request body, include the fields required when creating a new stage. The information you add in the request body will overwrite the existing stage’s details.
Retrieve stages
- To retrieve all stages in a pipeline, make a
GETrequest to/crm/v3/pipelines/{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/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}.
Update a stage
To edit a stage’s details, such as label or display order, make aPATCH request to /crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}. In the request body, include the properties to update.
Delete a stage
To delete a pipeline stage, make aDELETE request to /crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}.
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/v3/pipelines/{objectType}/{pipelineId}/audit. - To view changes made to a stage, make a
GETrequest to/crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}/audit.