Skip to main content
POST
/
crm
/
v3
/
pipelines
/
{objectType}
/
{pipelineId}
/
stages
Create a pipeline stage
curl --request POST \
  --url https://api.hubapi.com/crm/v3/pipelines/{objectType}/{pipelineId}/stages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "label": "Done",
  "displayOrder": 1,
  "metadata": {
    "ticketState": "CLOSED"
  }
}'
{
  "label": "In Progress",
  "displayOrder": 0,
  "metadata": {
    "ticketState": "OPEN"
  },
  "createdAt": "2019-10-30T03:30:17.883Z",
  "updatedAt": "2019-12-07T16:50:06.678Z",
  "archived": false,
  "id": "1234912"
}

Supported products

Requires one of the following products or higher.
Marketing HubMarketing Hub -Free
Sales HubSales Hub -Free
Service HubService Hub -Free
Content HubContent Hub -Starter
This API requires one of the following scopes:
crm.objects.carts.write
crm.objects.orders.write
crm.objects.users.write
crm.pipelines.orders.write
crm.schemas.appointments.write
crm.schemas.carts.write
crm.schemas.commercepayments.write
crm.schemas.companies.write
crm.schemas.contacts.write
crm.schemas.courses.write
crm.schemas.deals.write
crm.schemas.invoices.write
crm.schemas.listings.write
crm.schemas.orders.write
crm.schemas.services.write
crm.schemas.subscriptions.write
e-commerce
tickets
tickets.highly_sensitive.v2
tickets.sensitive.v2

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

​
objectType
string
required
​
pipelineId
string
required

Body

application/json

An input used to create or replace a pipeline stage's definition.

​
metadata
object
required

A JSON object containing properties that are not present on all object pipelines.

For deals pipelines, the probability field is required ({ "probability": 0.5 }), and represents the likelihood a deal will close. Possible values are between 0.0 and 1.0 in increments of 0.1.

For tickets pipelines, the ticketState field is optional ({ "ticketState": "OPEN" }), and represents whether the ticket remains open or has been closed by a member of your Support team. Possible values are OPEN or CLOSED.

​
displayOrder
integer
required

The order for displaying this pipeline stage. If two pipeline stages have a matching displayOrder, they will be sorted alphabetically by label.

​
label
string
required

A label used to organize pipeline stages in HubSpot's UI. Each pipeline stage's label must be unique within that pipeline.

Response

successful operation

A pipeline stage definition.

​
createdAt
string<date-time>
required

The date the pipeline stage was created. The stages on default pipelines will have createdAt = 0.

​
archived
boolean
required

Whether the pipeline is archived.

​
metadata
object
required

A JSON object containing properties that are not present on all object pipelines.

For deals pipelines, the probability field is required ({ "probability": 0.5 }), and represents the likelihood a deal will close. Possible values are between 0.0 and 1.0 in increments of 0.1.

For tickets pipelines, the ticketState field is optional ({ "ticketState": "OPEN" }), and represents whether the ticket remains open or has been closed by a member of your Support team. Possible values are OPEN or CLOSED.

​
displayOrder
integer
required

The order for displaying this pipeline stage. If two pipeline stages have a matching displayOrder, they will be sorted alphabetically by label.

​
label
string
required

A label used to organize pipeline stages in HubSpot's UI. Each pipeline stage's label must be unique within that pipeline.

​
id
string
required

A unique identifier generated by HubSpot that can be used to retrieve and update the pipeline stage.

​
updatedAt
string<date-time>
required

The date the pipeline stage was last updated.

​
archivedAt
string<date-time>

The date the pipeline was archived. archivedAt will only be present if the pipeline is archived.

​
writePermissions
enum<string>

Defines the level of write access for the pipeline stage, with possible values being CRM_PERMISSIONS_ENFORCEMENT, READ_ONLY, or INTERNAL_ONLY.

Available options:
CRM_PERMISSIONS_ENFORCEMENT,
READ_ONLY,
INTERNAL_ONLY