> ## 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.

# Deals

> API reference for Essal Sales deals — lifecycle management, stage transitions, activity logging, and closing.

## List Deals

`GET /v1/sales/deals`

**Query Parameters**

| Parameter     | Type   | Description                         |
| ------------- | ------ | ----------------------------------- |
| `pipeline_id` | string | Filter by pipeline                  |
| `stage_id`    | string | Filter by stage                     |
| `status`      | enum   | `open`, `won`, `lost`, `archived`   |
| `owner_id`    | string | Filter by deal owner                |
| `sort`        | string | e.g. `value:desc`, `created_at:asc` |

***

## Get a Deal

`GET /v1/sales/deals/{id}`

***

## Create a Deal

`POST /v1/sales/deals`

```json theme={null}
{
  "title": "Acme Corp — Enterprise Licence",
  "pipeline_id": "pip_01HXYZ1111",
  "stage_id": "stg_01HXYZ2222",
  "value": 72000,
  "currency": "GBP",
  "owner_id": "usr_01HXYZ5678",
  "contact_ids": ["cnt_01HXYZ9999"],
  "expected_close_date": "2026-09-30"
}
```

**Response** — `201 Created`

***

## Update a Deal

`PATCH /v1/sales/deals/{id}`

```json theme={null}
{ "stage_id": "stg_01HXYZ3333", "value": 80000 }
```

Updating `stage_id` fires a `sales.deal.stage_changed` event.

***

## Close a Deal

`POST /v1/sales/deals/{id}/close`

```json theme={null}
{
  "outcome": "won",
  "close_reason": "Contract signed"
}
```

Valid outcomes: `won`, `lost`. Fires `sales.deal.won` or `sales.deal.lost`.

***

## Log an Activity

`POST /v1/sales/deals/{id}/activities`

```json theme={null}
{
  "type": "call",
  "note": "Discussed pricing model.",
  "occurred_at": "2026-07-10T14:30:00Z"
}
```

Activity types: `call`, `email`, `meeting`, `note`, `task`.