API reference

Pipelines and stages

A pipeline is an ordered list of stages that leads move through. Every pipeline has one incoming stage and at least one open, one won and one lost stage.

The pipeline object

{
  "id": "pl_01j8z5y1b3c5d7e9f1g3h5j7k9",
  "name": { "uz-Latn": "Savdo", "ru": "Продажи", "en": "Sales" },
  "position": 0,
  "loss_reasons": [ { "id": "…", "name": { "uz-Latn": "Qimmat", "ru": "Дорого", "en": "Too expensive" } } ],
  "visible_to": null,
  "visible_teams": ["tm_01j8z6a2b4c6d8e0f2g4h6j8k0"],
  "hidden_from": ["mb_01j8z5x7y9z1a3b5c7d9e1f3g5"],
  "stages": [
    { "id": "st_01j8z5z0a2b4c6d8e0f2g4h6j8", "pipeline_id": "pl_01j8z5y1b3c5d7e9f1g3h5j7k9",
      "name": { "uz-Latn": "Yangi", "ru": "Новая", "en": "New" }, "type": "incoming", "position": 0, "color": "sky", "rotting_days": null }
  ]
}

• name fields are localized: pick the language you show.
• A stage's type is incoming (new leads land here), open, won or lost. Moving a lead to a won or lost stage closes it.
• A pipeline has exactly one incoming stage and may have several open, won and lost stages (for example "Paid in full" and "Paid in instalments"). Stages are grouped in that order: incoming, open, won, lost.
• Who sees the pipeline: visible_to (members) and visible_teams (teams) both null means everyone; otherwise the listed members plus everyone in the listed teams. hidden_from (always an array) hides it from those members even when a team opens it to them. Owners, admins and API keys always see every pipeline. A PATCH that sends only visible_to resets visible_teams to null.
• rotting_days: after how many days without progress a lead in this stage counts as stalled, or null.

Endpoints

Every pipeline with its stages, in order: {"data": [ … ]}. Use it to map stage ids to names and to find the stage to move a lead to.

Creating and changing pipelines and stages is reserved for owners and admins in Kweko (Settings → Pipelines); these endpoints do not accept API keys yet, although the pipelines:manage scope exists:

Adding a stage takes an optional type: open (the default), won or lost. The new stage goes after after when that stage is the same type, otherwise last in its group.

Reordering takes stage_ids: every stage of one type (open, won or lost), each once, in the new order. The groups themselves stay in place.

Deleting a stage that has leads needs ?move_to=st_… (stage_has_leads); leads of a won or lost stage move to another stage of the same type and stay closed. The incoming stage and the last stage of each type cannot be deleted (stage_required).