Pipelines

In HubSpot, a pipeline is where records are tracked through stages. For example, sales pipelines can be used to predict revenue and identify roadblocks or service pipelines can be used to manage ticket statuses and analyze blockers. Depending on your subscription, you can create multiple pipelines for an object. For example, when working with deals, an account might have one pipeline for New Sales and another for Contract Renewals.

Pipelines are available for the following objects:

• Deals
• Tickets
• Appointments
• Courses
• Listings
• Orders
• Services
• Leads (Sales Hub Professional and Enterprise only)
• Custom objects (Enterprise only)

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 a POST 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, probability is required with a value between 0.0 and 1.0, 0.0 being Closed Lost and 1.0 being Closed Won. For tickets, you can include ticketStatewith a value of either OPEN or CLOSED.
  • 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.

For example, to create a new deal pipeline, your request may look like the following:

If there's an existing pipeline you want to replace instead of creating a new pipeline, make a PUT 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.

• To retrieve all pipelines for an object, make a GET request to /crm/v3/pipelines/{objectType}. Each pipeline's id, label, and displayOrder values will be returned, along with information about when it was created or updated. You can use the id values to retrieve and update individual pipelines.
  
• To retrieve an individual pipeline, make a GET request to /crm/v3/pipelines/{objectType}/{pipelineId}.

To edit a pipeline's details, such as label or display order, make a PATCH 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.

To delete a pipeline, make a DELETE 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:

To add a new stage to a pipeline, make a POST 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, probability is  required with a value between 0.0 and 1.0, 0.0 being Closed Lost and 1.0 being Closed Won. For tickets, you can include ticketState with a value of OPEN or CLOSED.

For example, to add a stage called Contract signed as the fifth stage in a pipeline, you request would look like:

If there's an existing pipeline stage you want to replace instead of creating a new stage, make a PUT 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.

• To retrieve all stages in a pipeline, make a GET request to /crm/v3/pipelines/{objectType}/{pipelineId}/stages. Each stage's id, label, and displayOrder values will be returned, along with information about when it was created or updated. You can use the id values to retrieve and update individual stages.
  
• To retrieve an individual stage, make a GET request to /crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}.

To edit a stage's details, such as label or display order, make a PATCH request to /crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}. In the request body, include the properties to update. 

To delete a pipeline stage, make a DELETE request to /crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}.

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 GET request to /crm/v3/pipelines/{objectType}/{pipelineId}/audit.
• To view changes made to a stage, make a GET request to /crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}/audit.

In the response, updates are listed in reverse chronological order with details about the type of action, when it occurred, and who made the change.

For example, when auditing changes to a pipeline, your response would look like the following: