> ## Documentation Index
> Fetch the complete documentation index at: https://developers.essal.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Pipeline

> Configure sales pipeline stages, move deals through them via the API, and use webhooks to trigger downstream actions.

Essal Sales uses **Pipelines** to model your sales process. A pipeline is a linear sequence of stages. Deals are created in a pipeline and progress through stages until they are won, lost, or archived.

## Creating a Pipeline

```bash theme={null}
POST /v1/sales/pipelines
{
  "name": "Enterprise Sales",
  "stages": [
    { "name": "Prospecting", "order": 1, "probability": 10 },
    { "name": "Qualified", "order": 2, "probability": 30 },
    { "name": "Proposal Sent", "order": 3, "probability": 60 },
    { "name": "Negotiation", "order": 4, "probability": 80 },
    { "name": "Closed Won", "order": 5, "probability": 100 }
  ]
}
```

Each stage carries a `probability` percentage used for revenue forecasting.

## Moving a Deal Between Stages

```bash theme={null}
PATCH /v1/sales/deals/deal_01HXYZ5555
{
  "stage_id": "stg_01HXYZ3333",
  "stage_note": "Proposal accepted, moving to negotiation"
}
```

A `sales.deal.stage_changed` event fires automatically. You can attach webhooks to this event to trigger notifications, update CRM records, or kick off project onboarding in Essal Project.

## Board View via API

Retrieve all deals grouped by stage for a board-style UI:

```bash theme={null}
GET /v1/sales/pipelines/pip_01HXYZ1111/board
```

```json theme={null}
{
  "pipeline_id": "pip_01HXYZ1111",
  "stages": [
    {
      "id": "stg_01HXYZ2222",
      "name": "Prospecting",
      "deals": [
        { "id": "deal_01HXYZAAA", "title": "Acme Corp - Platform Licence", "value": 48000 }
      ]
    }
  ]
}
```

## Filtering and Sorting Deals

```bash theme={null}
GET /v1/sales/deals?pipeline_id=pip_01HXYZ1111&stage_id=stg_01HXYZ3333&sort=value:desc&limit=25
```

Supported filter parameters: `pipeline_id`, `stage_id`, `owner_id`, `contact_id`, `status`, `value_min`, `value_max`, `created_after`, `created_before`.

## Revenue Forecasting

Retrieve a weighted forecast for a pipeline:

```bash theme={null}
GET /v1/sales/pipelines/pip_01HXYZ1111/forecast?period=2026-Q3
```

The forecast endpoint multiplies each deal's `value` by its stage `probability` and returns a weighted total, broken down by stage and owner.

<Note>
  The forecast endpoint uses the deal value and stage probability at query time. It does not store historical snapshots — use the export endpoint to archive periodic forecast data.
</Note>