There's a new version of the HubSpot API

As of November 30, 2022, HubSpot API keys are no longer a supported authentication method for accessing HubSpot APIs. Instead, you should use a private app access token or OAuth to authenticate API calls. Learn more about this change and how to migrate an API key integration to use a private app instead.

Create a new pipeline

Last updated May 31, 2023

POST /crm-pipelines/v1/pipelines/:object_type

Method Details

HTTP Methods:

POST

Content Type:

application/json

Response Format:

json

Requires Authentication?

Yes

Rate Limited?

Yes

Headers

User-Agent

Products:

CRM and Service Hub

Create a new pipeline for the specified object type. Currently this supports deals and tickets.
Required Parameters How to use Description
OAuth access token or private app access token Authorization: Bearer {token} header Used to authenticate the request. Please see this page for more details about authentication.
Object Type /:object_type
Used in the request URL

The object type that you are creating the pipeline for.

Must be one of:

  • deals
  • tickets
label String; Used in the request JSON The label for the pipeline. The label will be displayed when viewing records in HubSpot. The label is limited to 36 characters.
displayOrder Integer; Used in the request JSON When viewing records in HubSpot, pipelines are displayed starting with the pipeline with the lowest displayOrder value.
active Boolean; Used in the request JSON Whether or not the pipeline is active. This should be true for new pipelines, otherwise they will not be available to use when updating or editing records.
stages List; Used in the request JSON A list of stages for this pipeline. Pipelines may have up to 100 stages. See the table below for the requirements for each stage.
pipelineId String; Used in the request JSON The internal ID for the new pipeline. The ID must be unique across pipelines for the specified object type. This ID will be automatically generated if not included when creating the pipeline. The ID is limied to 36 characters.

Each entry in the stages list must have the following fields:

Required Parameters How to use Description
stageId String The internal ID of the stage. These IDs must be unique across all stages for all pipelines for the specified object type. Each ID is limited to 36 characters. IDs must only contain numbers, dashes and lowercase numbers
label String The label for the stage. The label is what users will see when viewing records in HubSpot. Each label is limited to 36 characters.
displayOrder Integer When viewing records in HubSpot, stages are displayed starting with the stage with the lowest displayOrder value.

Metadata

In addition to the standard fields described above, pipelines stages can have a metadata field that includes object-specific stage information. This field is a JSON object containing properties that are not present on all object pipelines. The details for each object type’s metadata field can be found below:

For Deals Pipelines:

Deal pipeline stages have a single required metadata field.

Required Parameters How to use Description
metadata Object, included in the request JSON Required for Deals. An object representing the details of the pipeline:

“metadata”: {
    “probability”: 0.5
}

probability is the only required parameter in the metadata object. This parameter is the likelihood a deal will close. Possible values are between 0.0 and 1.0 in increments of 0.1

For Tickets Pipelines:

Ticket pipeline stages have a single optional metadata field.

Required Parameters How to use Description
metadata Object, included in the request JSON Optional for Tickets. An object representing the details of the pipeline:

“metadata”: {
    “ticketState”: "OPEN"
}

ticketState is the only optional parameter in the metadata object. This parameter can be set to either OPEN or CLOSED. It indicates if the ticket remains open or has been closed by a member of your Support team.