Update a Stage

Update Stage

curl --request PATCH \
  --url https://api.example.com/deals/stages/{stage_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "color": "<string>",
  "probability": 0.5,
  "is_won": true,
  "is_lost": true,
  "is_hidden": true,
  "position": 123
}
'

import requests

url = "https://api.example.com/deals/stages/{stage_id}"

payload = {
    "name": "<string>",
    "color": "<string>",
    "probability": 0.5,
    "is_won": True,
    "is_lost": True,
    "is_hidden": True,
    "position": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    color: '<string>',
    probability: 0.5,
    is_won: true,
    is_lost: true,
    is_hidden: true,
    position: 123
  })
};

fetch('https://api.example.com/deals/stages/{stage_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/deals/stages/{stage_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'color' => '<string>',
    'probability' => 0.5,
    'is_won' => true,
    'is_lost' => true,
    'is_hidden' => true,
    'position' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/deals/stages/{stage_id}"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"color\": \"<string>\",\n  \"probability\": 0.5,\n  \"is_won\": true,\n  \"is_lost\": true,\n  \"is_hidden\": true,\n  \"position\": 123\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.example.com/deals/stages/{stage_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"color\": \"<string>\",\n  \"probability\": 0.5,\n  \"is_won\": true,\n  \"is_lost\": true,\n  \"is_hidden\": true,\n  \"position\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/deals/stages/{stage_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"color\": \"<string>\",\n  \"probability\": 0.5,\n  \"is_won\": true,\n  \"is_lost\": true,\n  \"is_hidden\": true,\n  \"position\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

PATCH

deals

stages

{stage_id}

Update Stage

curl --request PATCH \
  --url https://api.example.com/deals/stages/{stage_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "color": "<string>",
  "probability": 0.5,
  "is_won": true,
  "is_lost": true,
  "is_hidden": true,
  "position": 123
}
'

import requests

url = "https://api.example.com/deals/stages/{stage_id}"

payload = {
    "name": "<string>",
    "color": "<string>",
    "probability": 0.5,
    "is_won": True,
    "is_lost": True,
    "is_hidden": True,
    "position": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    color: '<string>',
    probability: 0.5,
    is_won: true,
    is_lost: true,
    is_hidden: true,
    position: 123
  })
};

fetch('https://api.example.com/deals/stages/{stage_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/deals/stages/{stage_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'color' => '<string>',
    'probability' => 0.5,
    'is_won' => true,
    'is_lost' => true,
    'is_hidden' => true,
    'position' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/deals/stages/{stage_id}"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"color\": \"<string>\",\n  \"probability\": 0.5,\n  \"is_won\": true,\n  \"is_lost\": true,\n  \"is_hidden\": true,\n  \"position\": 123\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.example.com/deals/stages/{stage_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"color\": \"<string>\",\n  \"probability\": 0.5,\n  \"is_won\": true,\n  \"is_lost\": true,\n  \"is_hidden\": true,\n  \"position\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/deals/stages/{stage_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"color\": \"<string>\",\n  \"probability\": 0.5,\n  \"is_won\": true,\n  \"is_lost\": true,\n  \"is_hidden\": true,\n  \"position\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

All body fields are optional and partial — only fields present are changed. Setting position here is not atomic with other stages’ positions; use Reorder Stages for a bulk move.

Auth

Requires the org-admin scope organizations:manage specifically — the CRM manage scopes the rest of the deals router accepts are not enough here — plus an active organization on the token.

Response

The updated stage row — same shape as List All Stages. If the body has no non-null fields, returns the stage unchanged without a write.

Errors

Status	Cause
`404`	No stage with that id in this org.
`400`	Setting both `is_won` and `is_lost` true; or hiding the org’s last visible Won or last visible Lost stage — at least one of each must stay visible.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

stage_id

string

required

The pipeline stage's id.

Body

application/json

name

string | null

New stage name.

Required string length: 1 - 80

color

string | null

New hex color for the stage chip/column.

probability

number | null

New default win probability, 0.0-1.0.

Required range: 0 <= x <= 1

is_won

boolean | null

Toggle whether this is a Closed Won terminal stage.

is_lost

boolean | null

Toggle whether this is a Closed Lost terminal stage.

is_hidden

boolean | null

Hide the stage from non-admin views; blocked while it holds the last visible Won/Lost stage.

position

integer | null

New sort position.

Response

Successful Response

Contacts

Deals

Accounts

Activities

Tags

Files

Folders

Notifications

Reports

PATs

Integrations

AI

Analytics Assistant

Feedback

Customer Intelligence

Outreach

AnyCard

AnyCard Events

AnyCard Share Links

Public Media

Account Readiness

Service Health

Auth

Response

Errors

Authorizations

Path Parameters

Body

Response

​Auth

​Response

​Errors

Authorizations

Path Parameters

Body

Response

Auth

Response

Errors