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

# Track Deals

> Create and manage deal records in Essal Sales, log activities, and use the revenue forecasting API.

**Deals** are the core records in Essal Sales. A deal represents a potential business opportunity, linked to one or more contacts and progressing through a pipeline. This guide covers creating deals, logging activity, and reading deal summaries.

## Creating a Deal

```bash theme={null}
POST /v1/sales/deals
{
  "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"
}
```

```json theme={null}
{
  "id": "deal_01HXYZAAA",
  "title": "Acme Corp - Enterprise Licence",
  "status": "open",
  "stage": { "id": "stg_01HXYZ2222", "name": "Qualified" },
  "value": 72000,
  "currency": "GBP",
  "probability": 30,
  "weighted_value": 21600
}
```

## Logging Activities

Track all deal-related interactions in the activity log:

```bash theme={null}
POST /v1/sales/deals/deal_01HXYZAAA/activities
{
  "type": "call",
  "note": "Spoke with Jane re: pricing. She wants a revised proposal by EOW.",
  "occurred_at": "2026-07-10T14:30:00Z"
}
```

Supported activity types: `call`, `email`, `meeting`, `note`, `task`.

## Retrieving the Activity Timeline

```bash theme={null}
GET /v1/sales/deals/deal_01HXYZAAA/activities?limit=10&sort=occurred_at:desc
```

Each activity entry includes the type, author, timestamp, and note. Activities are immutable once created.

## Closing a Deal

Mark a deal as won or lost. Both transitions require a `close_reason`:

```bash theme={null}
# Mark as won
POST /v1/sales/deals/deal_01HXYZAAA/close
{
  "outcome": "won",
  "close_reason": "Signed contract received"
}

# Mark as lost
POST /v1/sales/deals/deal_01HXYZAAA/close
{
  "outcome": "lost",
  "close_reason": "Budget frozen until next fiscal year"
}
```

Closing fires either a `sales.deal.won` or `sales.deal.lost` event, which can trigger downstream automation — for example, kicking off project creation in Essal Project.

<Tip>
  Link a deal to an Essal Project at close-time using the `linked_resources` field on the project object. This gives your delivery team direct context on the business opportunity they are delivering.
</Tip>

## Deal Summary

Get a structured summary of a deal suitable for embedding in dashboards:

```bash theme={null}
GET /v1/sales/deals/deal_01HXYZAAA/summary
```

The summary response includes the deal's current stage, weighted value, activity count, days since last activity, and next scheduled task.