Create a Stage

Create Stage

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

import requests

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

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

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

print(response.text)

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

fetch('https://api.example.com/deals/stages', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'color' => '#6366F1',
    'probability' => 0.5,
    'is_won' => false,
    'is_lost' => false,
    '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"

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

	req, _ := http.NewRequest("POST", 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.post("https://api.example.com/deals/stages")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"color\": \"#6366F1\",\n  \"probability\": 0.5,\n  \"is_won\": false,\n  \"is_lost\": false,\n  \"position\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

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

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

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

POST

deals

stages

Create Stage

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

import requests

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

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

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

print(response.text)

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

fetch('https://api.example.com/deals/stages', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'color' => '#6366F1',
    'probability' => 0.5,
    'is_won' => false,
    'is_lost' => false,
    '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"

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

	req, _ := http.NewRequest("POST", 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.post("https://api.example.com/deals/stages")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"color\": \"#6366F1\",\n  \"probability\": 0.5,\n  \"is_won\": false,\n  \"is_lost\": false,\n  \"position\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

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

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

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

key is derived automatically from name (lowercased, non-alphanumerics collapsed to _). is_closed is set to is_won OR is_lost. When position is omitted, the stage is placed immediately after the last non-terminal stage and before Won/Lost — any stage already at or past that slot is shifted up by one first, since (org_id, position) isn’t a unique constraint and a tie would sort unpredictably.

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 created stage row — same shape as List All Stages.

Errors

Status	Cause
`400`	`is_won` and `is_lost` both `true`.

Authorizations

Authorization

string

header

required

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

Body

application/json

name

string

required

Stage name, shown on the pipeline board.

Required string length: 1 - 80

color

string

default:#6366F1

Hex color for the stage chip/column.

probability

number | null

Default win probability for deals in this stage, 0.0-1.0.

Required range: 0 <= x <= 1

is_won

boolean

default:false

Mark this as the (or a) Closed Won terminal stage.

is_lost

boolean

default:false

Mark this as the (or a) Closed Lost terminal stage.

position

integer | null

Sort position; defaults to just before the terminal stages when omitted.

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

Body

Response

​Auth

​Response

​Errors

Authorizations

Body

Response

Auth

Response

Errors