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

# Deals API

> Manage deals and opportunities in your pipeline

## Overview

The Deals API provides endpoints for managing deals, tracking pipeline stages, and forecasting revenue.

**Base Path**: `/api/deals`

## Endpoints

### List Deals

```bash theme={null}
GET /api/deals
```

**Query Parameters**:

| Parameter    | Type    | Description              |
| ------------ | ------- | ------------------------ |
| `page`       | integer | Page number              |
| `page_size`  | integer | Items per page           |
| `company_id` | UUID    | Filter by company        |
| `stage`      | string  | Filter by pipeline stage |
| `owner_id`   | UUID    | Filter by deal owner     |
| `value_min`  | number  | Minimum deal value       |
| `value_max`  | number  | Maximum deal value       |

**Example**:

```bash theme={null}
curl -H "Authorization: Bearer TOKEN" \
  "http://localhost:8000/api/deals?stage=pipeline&value_min=100000"
```

**Response**:

```json theme={null}
{
  "data": [
    {
      "id": "hh0e8400-e29b-41d4-a716-446655442222",
      "name": "Enterprise Deal - Acme Corp",
      "company_id": "550e8400-e29b-41d4-a716-446655440000",
      "company_name": "Acme Corp",
      "value": 250000,
      "stage": "pipeline",
      "probability": 75,
      "owner_id": "user-uuid",
      "owner_name": "John Doe",
      "close_date": "2024-03-15",
      "created_at": "2024-01-10T09:00:00Z",
      "updated_at": "2024-01-20T14:30:00Z"
    }
  ],
  "total": 42,
  "total_value": 8500000
}
```

### Create Deal

```bash theme={null}
POST /api/deals
```

**Request Body**:

```json theme={null}
{
  "name": "Strategic Partnership",
  "company_id": "550e8400-e29b-41d4-a716-446655440000",
  "value": 150000,
  "stage": "qualification",
  "probability": 50,
  "close_date": "2024-04-30",
  "description": "Partnership opportunity for platform integration"
}
```

**Response** (201 Created):

```json theme={null}
{
  "id": "ii0e8400-e29b-41d4-a716-446655443333",
  "name": "Strategic Partnership",
  "company_id": "550e8400-e29b-41d4-a716-446655440000",
  "value": 150000,
  "stage": "qualification",
  "probability": 50,
  "close_date": "2024-04-30",
  "created_at": "2024-01-22T12:00:00Z"
}
```

## Pipeline Stages

| Stage           | Description           | Typical Probability |
| --------------- | --------------------- | ------------------- |
| `lead`          | Initial lead          | 10-20%              |
| `qualification` | Qualified opportunity | 25-40%              |
| `proposal`      | Proposal submitted    | 50-60%              |
| `negotiation`   | In negotiation        | 70-80%              |
| `closed_won`    | Deal won              | 100%                |
| `closed_lost`   | Deal lost             | 0%                  |

## Deal Object

| Field         | Type      | Description             |
| ------------- | --------- | ----------------------- |
| `id`          | UUID      | Unique identifier       |
| `name`        | string    | Deal name               |
| `company_id`  | UUID      | Associated company      |
| `value`       | number    | Deal value in USD       |
| `stage`       | enum      | Pipeline stage          |
| `probability` | integer   | Win probability (0-100) |
| `owner_id`    | UUID      | Deal owner              |
| `close_date`  | date      | Expected close date     |
| `description` | text      | Deal description        |
| `created_at`  | timestamp | Creation timestamp      |
| `updated_at`  | timestamp | Last update             |

## Examples

### TypeScript

```typescript theme={null}
// Get pipeline deals
const deals = await fetch('http://localhost:8000/api/deals?stage=pipeline', {
  headers: { 'Authorization': `Bearer ${token}` }
}).then(r => r.json())

// Create deal
const newDeal = await fetch('http://localhost:8000/api/deals', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Enterprise Deal',
    company_id: companyId,
    value: 200000,
    stage: 'qualification'
  })
}).then(r => r.json())
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Companies API" icon="building" href="/api-reference/companies">
    Company management
  </Card>

  <Card title="Contacts API" icon="user" href="/api-reference/contacts">
    Contact management
  </Card>

  <Card title="Reports API" icon="chart-line" href="/api-reference/reports">
    Generate deal reports
  </Card>
</CardGroup>