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

# HubSpot Deal Management

> Mid-call action for real-time access to HubSpot deals and sales pipeline management during customer conversations

# HubSpot Deal Management Template

Enhance your AI assistant with the capability to access HubSpot deals directly during customer calls, update deal statuses, and provide sales pipeline information.

## Overview

<CardGroup cols={2}>
  <Card title="Deal Query" icon="search">
    * Automatic access to existing deals
    * Real-time status updates
    * Pipeline stage tracking
    * Deal value and probability
  </Card>

  <Card title="Sales Automation" icon="robot">
    * Automatic deal creation
    * Status updates based on conversation
    * Schedule follow-up activities
    * Send team notifications
  </Card>
</CardGroup>

## Configuring the Deal Query Tool

### 1. Basic Configuration

<Tabs>
  <Tab title="Tool Settings">
    | Parameter         | Value                                                                                                       |
    | ----------------- | ----------------------------------------------------------------------------------------------------------- |
    | **Function Name** | `get_hubspot_deals`                                                                                         |
    | **Description**   | "Fetches current deals of a contact from HubSpot. Use this when discussing existing projects or proposals." |
    | **HTTP Method**   | `GET`                                                                                                       |
    | **Timeout**       | `6000ms`                                                                                                    |
  </Tab>

  <Tab title="API Configuration">
    ```yaml theme={null}
    URL: https://api.hubapi.com/crm/v3/objects/deals/search

    Headers:
      Authorization: "Bearer IHRE_HUBSPOT_API_KEY"
      Content-Type: "application/json"

    Method: POST (for Search API)
    ```
  </Tab>
</Tabs>

### 2. Request Body for Deal Search

```json theme={null}
{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "associatedcontactid",
          "operator": "EQ",
          "value": "{contact_id}"
        }
      ]
    }
  ],
  "properties": [
    "dealname",
    "dealstage", 
    "amount",
    "closedate",
    "pipeline",
    "probability",
    "createdate",
    "hs_deal_priority",
    "description"
  ],
  "sorts": [
    {
      "propertyName": "hs_lastmodifieddate",
      "direction": "DESCENDING"
    }
  ],
  "limit": 10
}
```

### 3. Parameter Schema

```json theme={null}
{
  "type": "object",
  "properties": {
    "contact_id": {
      "type": "string",
      "description": "HubSpot contact ID for deal search"
    },
    "deal_stage": {
      "type": "string", 
      "description": "Filter by specific deal stage (optional)",
      "enum": ["prospecting", "qualification", "needs-analysis", "proposal", "negotiation", "closed-won", "closed-lost"]
    },
    "include_closed": {
      "type": "boolean",
      "description": "Include closed deals?",
      "default": false
    }
  },
  "required": ["contact_id"]
}
```

## Configuring the Deal Update Tool

### 1. Updating Deal Status

<AccordionGroup>
  <Accordion title="Tool Configuration">
    | Parameter         | Value                                                                                       |
    | ----------------- | ------------------------------------------------------------------------------------------- |
    | **Function Name** | `update_hubspot_deal`                                                                       |
    | **Description**   | "Updates the status or details of an existing HubSpot deal based on the conversation flow." |
    | **HTTP Method**   | `PATCH`                                                                                     |
    | **URL**           | `https://api.hubapi.com/crm/v3/objects/deals/{deal_id}`                                     |
  </Accordion>

  <Accordion title="Request Body">
    ```json theme={null}
    {
      "properties": {
        "dealstage": "{new_stage}",
        "hs_deal_priority": "{priority}",
        "notes_last_updated": "{current_timestamp}",
        "hs_deal_stage_probability": "{probability}",
        "description": "{updated_description}"
      }
    }
    ```
  </Accordion>

  <Accordion title="Parameter Schema">
    ```json theme={null}
    {
      "type": "object",
      "properties": {
        "deal_id": {
          "type": "string",
          "description": "ID of the deal to update"
        },
        "new_stage": {
          "type": "string",
          "description": "New deal stage",
          "enum": ["prospecting", "qualification", "needs-analysis", "proposal", "negotiation", "closed-won", "closed-lost"]
        },
        "priority": {
          "type": "string",
          "description": "Deal priority",
          "enum": ["low", "medium", "high"]
        },
        "notes": {
          "type": "string",
          "description": "Conversation notes or updates"
        }
      },
      "required": ["deal_id", "new_stage"]
    }
    ```
  </Accordion>
</AccordionGroup>

## Deal Creation Tool

### Automatic Deal Generation

<Tabs>
  <Tab title="Basic Tool">
    ```yaml theme={null}
    FunctionName: create_hubspot_deal
    HTTP-Method: POST
    URL: https://api.hubapi.com/crm/v3/objects/deals

    Description: "Creates a new deal in HubSpot based on the current conversation and customer requirements."
    ```
  </Tab>

  <Tab title="Request Structure">
    ```json theme={null}
    {
      "properties": {
        "dealname": "{deal_name}",
        "dealstage": "prospecting",
        "pipeline": "default",
        "amount": "{estimated_value}",
        "closedate": "{estimated_close_date}",
        "hubspot_owner_id": "{owner_id}",
        "description": "{deal_description}",
        "hs_deal_priority": "medium",
        "leadsource": "phone_call"
      },
      "associations": [
        {
          "to": {
            "id": "{contact_id}"
          },
          "types": [
            {
              "associationCategory": "HUBSPOT_DEFINED",
              "associationTypeId": 3
            }
          ]
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Parameter Schema">
    ```json theme={null}
    {
      "type": "object",
      "properties": {
        "deal_name": {
          "type": "string",
          "description": "Name of the new deal"
        },
        "contact_id": {
          "type": "string", 
          "description": "HubSpot contact ID"
        },
        "estimated_value": {
          "type": "number",
          "description": "Estimated deal value in euros"
        },
        "estimated_close_date": {
          "type": "string",
          "format": "date",
          "description": "Expected close date (YYYY-MM-DD)"
        },
        "owner_id": {
          "type": "string",
          "description": "HubSpot user ID of the responsible sales staff"
        },
        "deal_description": {
          "type": "string",
          "description": "Description of the deal based on the conversation"
        }
      },
      "required": ["deal_name", "contact_id"]
    }
    ```
  </Tab>
</Tabs>

## Combined Workflow Tool

### Intelligent Deal Management

```mermaid theme={null}
flowchart TD
    A[Conversation starts] --> B{Contact known?}
    B -->|Yes| C[get_hubspot_deals]
    B -->|No| D[get_hubspot_contact first]
    D --> C
    C --> E{Deals present?}
    E -->|Yes| F[Discuss existing deals]
    E -->|No| G{Purchase interest detected?}
    F --> H{Update deal needed?}
    G -->|Yes| I[create_hubspot_deal]
    G -->|No| J[Continue conversation]
    H -->|Yes| K[update_hubspot_deal]
    H -->|No| L[Plan follow-up]
    I --> M[Collect deal details]
    K --> N[Confirm with customer]
```

## Practical Use Cases

### Scenario 1: Existing Customer Calls

<Steps>
  <Step title="Customer Identification">
    * AI identifies customer by email/phone
    * Automatically fetch deals for this contact
  </Step>

  <Step title="Intelligent Conversation Guidance">
    ```yaml theme={null}
    If active deals exist:
      "I see we currently have a proposal for [Deal Name]. 
       How can I assist you with this?"

    If deal is in negotiation:
      "Do you have any questions regarding our proposal from [Date]? 
       The deal value is [Amount]."

    If no active deals:
      "How can I help you today? Are you planning a new project?"
    ```
  </Step>

  <Step title="Automatic Updates">
    * Update deal stage based on conversation
    * Add conversation notes
    * Define next steps
  </Step>
</Steps>

### Scenario 2: Lead Qualification with Deal Creation

<AccordionGroup>
  <Accordion title="BANT Qualification">
    **Budget Identification**:

    ```yaml theme={null}
    AI recognizes budget statements:
      "Our budget is approximately €50,000"
      → create_hubspot_deal with amount: 50000

    "We don't have a fixed budget yet"
      → Deal with amount: 0, note: "Budget to be clarified"
    ```
  </Accordion>

  <Accordion title="Authority Check">
    **Check decision-making authority**:

    ```yaml theme={null}
    Decision maker identified:
      → Deal priority: "high"
      → Owner: Senior Sales Rep

    Influencer / Gatekeeper:
      → Deal priority: "medium" 
      → Next step: Decision maker meeting
    ```
  </Accordion>

  <Accordion title="Need & Timeline">
    **Needs and timeline**:

    ```yaml theme={null}
    Urgent need:
      → closedate: +30 days
      → hs_deal_priority: "high"

    Long-term planning:
      → closedate: +6 months
      → dealstage: "prospecting"
    ```
  </Accordion>
</AccordionGroup>

## Response Processing

### Deal Query Response

```json theme={null}
{
  "results": [
    {
      "id": "deal123",
      "properties": {
        "dealname": "Website Redesign Project",
        "dealstage": "proposal",
        "amount": "15000",
        "closedate": "2024-03-15",
        "pipeline": "sales-pipeline",
        "probability": "60",
        "createdate": "2024-01-15T10:00:00.000Z",
        "hs_deal_priority": "high",
        "description": "Complete website redesign with CMS"
      }
    }
  ]
}
```

### Natural Language Usage

<Tabs>
  <Tab title="Deal Status Updates">
    ```yaml theme={null}
    Deal in Proposal Stage:
      "I see our proposal for the Website Redesign Project 
       is still under evaluation. Do you have any questions?"

    Deal in Negotiation:
      "Regarding the €15,000 offer - can we finalize the last details today?"

    Deal Close to Completion:
      "Perfect! The planned project start is March 15th. 
       Should we prepare the contract documents?"
    ```
  </Tab>

  <Tab title="Automatic Updates">
    ```yaml theme={null}
    Customer shows interest:
      → update_deal: dealstage = "needs-analysis"
      → add_note: "Customer very interested, discussed details"

    Customer raises objections:
      → update_deal: hs_deal_priority = "medium"  
      → add_note: "Objections: budget concerns, follow-up needed"

    Positive signals:
      → update_deal: probability = "80"
      → add_note: "Green light from customer, close likely"
    ```
  </Tab>
</Tabs>

## Advanced Features

### Pipeline Management

<CardGroup cols={2}>
  <Card title="Multi-Pipeline Support" icon="sitemap">
    **Different sales processes**:

    * Standard Sales Pipeline
    * Enterprise Sales Pipeline
    * Partner/Channel Pipeline
    * Renewal Pipeline
  </Card>

  <Card title="Custom Deal Properties" icon="sliders">
    **Industry-specific fields**:

    * Project scope
    * Technical requirements
    * Compliance requirements
    * ROI expectations
  </Card>
</CardGroup>

### Deal Forecasting

```yaml theme={null}
Intelligent close prediction:
  Factors:
    - Current deal stage
    - Historical conversion rates
    - Customer engagement level
    - Competitive situation
  
  Output:
    - Adjusted close probability
    - Recommended next steps
    - Risk assessment
```

## Integration with Other HubSpot Tools

### Workflow Combination

```mermaid theme={null}
sequenceDiagram
    participant C as Customer
    participant AI as AI Assistant  
    participant CT as Contact Tool
    participant DT as Deal Tool
    participant TT as Task Tool
    participant NT as Notification Tool
    
    C->>AI: "Can we discuss the proposal?"
    AI->>CT: get_contact(email)
    CT-->>AI: contact ID + details
    AI->>DT: get_deals(contact_id)
    DT-->>AI: deal list + status
    AI->>C: "Sure! I see our €15k proposal..."
    C->>AI: "We want to start the project"
    AI->>DT: update_deal(stage: "closed-won")
    AI->>TT: create_task("Plan project kickoff")
    AI->>NT: notify_sales_team("Deal closed!")
    AI->>C: "Great! I'll initiate everything..."
```

## Error Handling & Best Practices

### Robust Error Handling

<AccordionGroup>
  <Accordion title="Catch API Errors">
    **Deal not found (404)**:

    ```yaml theme={null}
    Cause: Deal ID does not exist or was deleted
    Fallback: "It seems this project is no longer current. 
              Let’s talk about your current needs."
    ```
  </Accordion>

  <Accordion title="Permission Error (403)">
    ```yaml theme={null}
    Cause: API key lacks permission for deals
    Fallback: "I currently can't access our project database. 
              I’ll still be happy to assist you."
    Action: Notify admin about permission issue
    ```
  </Accordion>

  <Accordion title="Rate Limiting (429)">
    ```yaml theme={null}
    Handling: 
      - Automatic retry with exponential backoff
      - Temporary fallback: "One moment, loading your project data..."
      - After 3 attempts: graceful degradation
    ```
  </Accordion>
</AccordionGroup>

### Performance Optimization

<Tabs>
  <Tab title="Selective Loading">
    ```yaml theme={null}
    Load only relevant deal properties:
      Standard: dealname, dealstage, amount, closedate
      As needed: description, custom_properties
      Avoid: associations, notes (large data volumes)
    ```
  </Tab>

  <Tab title="Smart Caching">
    ```yaml theme={null}
    Deal cache strategy:
      Active deals: cache for 5 minutes
      Closed deals: cache for 1 hour  
      Recently modified: invalidate via webhooks
    ```
  </Tab>
</Tabs>

## Analytics & Reporting

### Key Performance Indicators

| Metric                     | Description                  | Target                    |
| -------------------------- | ---------------------------- | ------------------------- |
| **Deal Conversion Rate**   | Conversation → Deal creation | >15%                      |
| **Stage Progression**      | Average stage movement       | +1 stage per conversation |
| **Close Rate Improvement** | Improvement via tool usage   | +20%                      |
| **Response Time**          | Deal tool performance        | \<3 seconds               |

### Success Tracking

<Steps>
  <Step title="Establish Baseline">
    * Measure conversion rates before tool implementation
    * Document average deal sizes
    * Capture sales cycle lengths
  </Step>

  <Step title="Measure Tool Impact">
    * Compare conversations with vs. without tool usage
    * Analyze deal quality scores
    * Collect customer experience feedback
  </Step>

  <Step title="Continuous Optimization">
    * Weekly performance reviews
    * Monthly tool configuration adjustments
    * Quarterly business impact assessments
  </Step>
</Steps>

***

<Card title="Further Integrations" icon="link">
  Expand your HubSpot deal management with additional tools:

  * [HubSpot Contact Retrieval](/en/automation-platform/mid-call-tools/integration-templates/hubspot-kontakt-abruf) for customer data
  * [HubSpot Lead Creation](/en/automation-platform/mid-call-tools/integration-templates/hubspot-lead-erstellung) for lead nurturing
  * [Webhook Integration](/en/automation-platform/mid-call-tools/integration-templates/webhook-automation) for complex workflows
</Card>

<Warning>
  **Important Note**: Deal updates directly affect sales forecasting and team performance. Ensure your sales team is informed about the automatic updates and define clear rules for critical deal changes.
</Warning>

<Tip>
  Need a whole toolset instead of building HTTP actions one by one? Connect an external **MCP server** — tools are discovered automatically. See [MCP Servers](/en/platform/mcp-servers).
</Tip>