Replace the pipeline stages (tenant:crm:admin)
PUT /api/crm/v1/stages
Module: CRM · operationId: replaceStages · Tag: Pipeline · Auth: access token (Authorization: Bearer <accessToken>)
Saves the whole list; its order is the order of the pipeline. Every phase needs at least one
active stage and keys must be unique (400, invalid_stages); a key that opportunities use
cannot be left out, only archived (400, stage_in_use). The phase of a stage that opportunities use
cannot change (400, field items.<n>.phase); add a new stage instead. Emits crm.stages.updated.
Request body
application/json (required)
items(array of StageInput, required): In pipeline order.key(string, required): Stable key of the stage. (max length 64)label(string, required): Display name. (max length 100)phase(string, required): Phase the stage belongs to. (one ofopen,won,lost)archived(boolean): Archived stages cannot be chosen for opportunities. (defaultfalse)probability(integer): Default win probability of an opportunity entering the stage. (default0; max 100)
Example:
{
"items": [
{
"key": "PROSPECTING",
"label": "Akquise",
"phase": "open",
"probability": 10
},
{
"key": "PROPOSAL",
"label": "Angebot",
"phase": "open",
"probability": 50
},
{
"key": "CLOSED_WON",
"label": "Gewonnen",
"phase": "won",
"probability": 100
},
{
"key": "CLOSED_LOST",
"label": "Verloren",
"phase": "lost",
"probability": 0
}
]
}
Responses
- 200 The saved stages (
application/json) - 400 Invalid input (
invalid):fieldnames the first invalid field,details.fieldsevery one (JSON paths for bodies, parameter names for the query). Some refusals have their own code (invalid_sort,invalid_stages,invalid_custom_fields,convert_target_required,invalid_csv, …). (application/json) - 401 Missing, invalid or expired token (no body).
- 403 The token lacks the permission (
insufficient permissions) or has no active tenant. (application/json) - 500 Unexpected error; details are only logged. (
application/json)
Fields of the 200 answer:
default(boolean, required): The tenant has not saved its own stages; these are the defaults.items(array of Stage, required): Stages in pipeline order.archived(boolean, required): Archived stages cannot be chosen for opportunities.key(string, required): Stable key of the stage (stored on opportunities). (max length 64)label(string, required): Display name. (max length 100)phase(string, required): Phase the stage belongs to. (one ofopen,won,lost)position(integer, required): Order in the pipeline.probability(integer, required): Default win probability of an opportunity entering the stage. (max 100)used(boolean, required, read-only): Opportunities are in the stage; it can then only be archived, not removed.
Example 200 answer:
{
"default": false,
"items": [
{
"archived": false,
"key": "PROSPECTING",
"label": "Erstkontakt",
"phase": "open",
"position": 1,
"probability": 10,
"used": true
},
{
"archived": false,
"key": "QUALIFICATION",
"label": "Qualifizierung",
"phase": "open",
"position": 2,
"probability": 30,
"used": true
},
{
"archived": false,
"key": "PROPOSAL",
"label": "Angebot",
"phase": "open",
"position": 3,
"probability": 50,
"used": true
},
{
"archived": false,
"key": "NEGOTIATION",
"label": "Verhandlung",
"phase": "open",
"position": 4,
"probability": 75,
"used": false
},
{
"archived": false,
"key": "CLOSED_WON",
"label": "Gewonnen",
"phase": "won",
"position": 5,
"probability": 100,
"used": true
},
{
"archived": false,
"key": "CLOSED_LOST",
"label": "Verloren",
"phase": "lost",
"position": 6,
"probability": 0,
"used": true
}
]
}
Example request
curl -X PUT 'https://api.mbcom.cloud/api/crm/v1/stages' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"items":[{"key":"PROSPECTING","label":"Akquise","phase":"open","probability":10},{"key":"PROPOSAL","label":"Angebot","phase":"open","probability":50},{"key":"CLOSED_WON","label":"Gewonnen","phase":"won","probability":100},{"key":"CLOSED_LOST","label":"Verloren","phase":"lost","probability":0}]}'