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

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:

curl -H "Authorization: Bearer TOKEN" \
  "http://localhost:8000/api/deals?stage=pipeline&value_min=100000"

Response:

{
  "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

POST /api/deals

Request Body:

{
  "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):

{
  "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

// 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

Companies API

Company management

Contacts API

Contact management

Reports API

Generate deal reports