Skip to main content

Deals API

The Deals API allows you to track win/loss deals and analyze competitive outcomes. Deals create DEAL and ARGUMENT nodes in the knowledge graph.

List Deals​

List all deals for the current workspace. Optionally filter by competitor ID.

GET /api/deals?competitorId={competitorId}

Query Parameters​

  • competitorId (string, optional) - Filter deals by competitor ID

Response​

{
  "deals": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "workspaceId": "workspace-id",
      "prospectCompanyName": "Acme Corp",
      "prospectIndustry": "Technology",
      "outcome": "WON",
      "competitorId": null,
      "decisionDate": "2024-01-15",
      "dealSize": "$100K",
      "arguments": ["Strong ROI", "Better integration"],
      "createdAt": "2024-01-01T00:00:00.000Z",
      "createdByUserId": "user-id"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "workspaceId": "workspace-id",
      "prospectCompanyName": "Beta Inc",
      "prospectIndustry": "Healthcare",
      "outcome": "LOST",
      "competitorId": "competitor-id",
      "decisionDate": "2024-01-20",
      "dealSize": "$50K",
      "arguments": ["Lower price", "Faster implementation"],
      "createdAt": "2024-01-01T00:00:00.000Z",
      "createdByUserId": "user-id"
    }
  ]
}

Get Deal​

Get a specific deal by ID.

GET /api/deals/{id}

Path Parameters​

  • id (string, required) - Deal ID

Response​

{
  "deal": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "workspace-id",
    "prospectCompanyName": "Acme Corp",
    "prospectIndustry": "Technology",
    "outcome": "WON",
    "competitorId": null,
    "decisionDate": "2024-01-15",
    "dealSize": "$100K",
    "arguments": ["Strong ROI", "Better integration"],
    "createdAt": "2024-01-01T00:00:00.000Z",
    "createdByUserId": "user-id"
  }
}

Create Deal​

Create a new deal. Requires EDITOR role or higher. Creates DEAL and ARGUMENT nodes in the knowledge graph.

POST /api/deals

Request Body​

{
  "prospectCompanyName": "Acme Corp",
  "prospectIndustry": "Technology",
  "outcome": "WON",
  "competitorId": null,
  "decisionDate": "2024-01-15",
  "dealSize": "$100K",
  "arguments": ["Strong ROI", "Better integration"]
}

Required Fields​

  • prospectCompanyName (string) - Name of the prospect company
  • outcome (string) - Must be "WON" or "LOST"
  • competitorId (string, required if outcome is "LOST") - Competitor ID when deal was lost

Optional Fields​

  • prospectIndustry (string) - Industry of the prospect
  • decisionDate (string) - Date of decision (ISO date format)
  • dealSize (string) - Size of the deal (e.g., "$100K", "$1M")
  • arguments (array of strings) - Reasons for win/loss

Response​

{
  "deal": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "workspace-id",
    "prospectCompanyName": "Acme Corp",
    "prospectIndustry": "Technology",
    "outcome": "WON",
    "competitorId": null,
    "decisionDate": "2024-01-15",
    "dealSize": "$100K",
    "arguments": ["Strong ROI", "Better integration"],
    "createdAt": "2024-01-01T00:00:00.000Z",
    "createdByUserId": "user-id"
  }
}

Update Deal​

Update an existing deal. Requires EDITOR role or higher.

PATCH /api/deals/{id}

Path Parameters​

  • id (string, required) - Deal ID

Request Body​

All fields are optional. Only include fields you want to update:

{
  "prospectCompanyName": "Updated Company Name",
  "outcome": "LOST",
  "competitorId": "competitor-id",
  "decisionDate": "2024-01-20",
  "dealSize": "$50K",
  "arguments": ["Lower price"]
}

Response​

{
  "deal": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "workspace-id",
    "prospectCompanyName": "Updated Company Name",
    "outcome": "LOST",
    "competitorId": "competitor-id",
    "decisionDate": "2024-01-20",
    "dealSize": "$50K",
    "arguments": ["Lower price"],
    "createdAt": "2024-01-01T00:00:00.000Z",
    "createdByUserId": "user-id"
  }
}

Delete Deal​

Delete a deal. Requires EDITOR role or higher.

DELETE /api/deals/{id}

Path Parameters​

  • id (string, required) - Deal ID

Response​

{
  "success": true
}

Error Responses​

  • 400 - Bad Request (missing required fields, invalid outcome, missing competitorId for LOST deals)
  • 401 - Unauthorized (invalid or missing API key)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not Found (deal doesn't exist)

Knowledge Graph Integration​

When a deal is created:

  • A DEAL node is created in the knowledge graph
  • ARGUMENT nodes are created for each argument/reason
  • Relationships are established between the deal, prospect, and competitor (if applicable)

These nodes can be visualized in the knowledge graph and used for competitive analysis.