home / skills / abdullahbeam / nexus-design-abdullah / hubspot-create-deal

hubspot-create-deal skill

/00-system/skills/hubspot/hubspot-create-deal

This skill creates a new HubSpot deal from your input, populating name, amount, stage, and close date for streamlined CRM entry.

npx playbooks add skill abdullahbeam/nexus-design-abdullah --skill hubspot-create-deal

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.4 KB

---
name: hubspot-create-deal
description: "Create a new deal in HubSpot CRM. Load when user says 'create deal', 'add deal', 'new deal', 'new opportunity'. Requires name, optional amount, stage, closedate."
---

# Create HubSpot Deal

**Specialized skill** for creating deals in HubSpot CRM.

## Pre-Flight Check

Before running, execute config check:
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/check_hubspot_config.py --json
```

If `ai_action` is not `proceed_with_operation`, follow hubspot-connect setup guide.

---

## Usage

### Required Parameters
- `--name` - Deal name (required)

### Optional Parameters
- `--amount` - Deal value in dollars
- `--stage` - Deal stage ID
- `--closedate` - Expected close date (YYYY-MM-DD)
- `--pipeline` - Pipeline ID (uses default if not specified)

### Examples

**Minimal (name only):**
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/create_deal.py \
  --name "New Enterprise Deal" \
  --json
```

**Full deal:**
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/create_deal.py \
  --name "Acme Corp - Enterprise" \
  --amount 50000 \
  --stage "qualifiedtobuy" \
  --closedate "2025-03-15" \
  --json
```

---

## Common Deal Stages

| Stage ID | Name |
|----------|------|
| appointmentscheduled | Appointment Scheduled |
| qualifiedtobuy | Qualified to Buy |
| presentationscheduled | Presentation Scheduled |
| decisionmakerboughtin | Decision Maker Bought In |
| contractsent | Contract Sent |
| closedwon | Closed Won |
| closedlost | Closed Lost |

---

## Output Format

```json
{
  "id": "5840795376",
  "properties": {
    "dealname": "Acme Corp - Enterprise",
    "amount": "50000",
    "dealstage": "qualifiedtobuy",
    "closedate": "2025-03-15T00:00:00Z",
    "createdate": "2025-12-13T10:00:00Z"
  }
}
```

---

## Display Format

```
✅ Deal created!
  ID: 5840795376
  Name: Acme Corp - Enterprise
  Amount: $50,000
  Stage: Qualified to Buy
  Close Date: 2025-03-15
```

---

## Error Handling

| Error | Solution |
|-------|----------|
| 401 | Invalid token - re-run setup |
| 403 | Missing `crm.objects.deals.write` scope |
| 400 | Invalid stage ID - check stage list |
| 429 | Rate limited - wait and retry |

---

## Related Skills

- `hubspot-list-deals` - List all deals
- `hubspot-update-deal` - Update deal stage/amount
- `hubspot-search-deals` - Find existing deals
- `hubspot-get-associations` - Link contacts to deal

Overview

This skill creates a new deal in HubSpot CRM from a simple command. It accepts a required name and optional amount, stage, close date, and pipeline to record opportunities quickly and consistently. The skill validates configuration before running and returns the created deal ID and key properties on success.

How this skill works

Before creating a deal the skill runs a configuration check to ensure HubSpot credentials and scopes are correct. It then calls the HubSpot Deals API with the provided name and any optional fields (amount, stage, closedate, pipeline). On success it returns a JSON object with the new deal ID and properties and prints a compact summary for human review.

When to use it

Create a new opportunity from chat or a command without opening the HubSpot UI.
Quickly record inbound leads or sales-qualified conversations into HubSpot.
Automate deal creation from workflows, scripts, or integrations.
Seed deals with estimated amount and expected close date during qualification.
Create a placeholder deal when you only have the name and will add details later.

Best practices

Always run the pre-flight config check to confirm authentication and required scopes.
Provide ISO date (YYYY-MM-DD) for closedate to avoid timezone issues.
Use numeric amount in dollars (no currency symbol) to ensure correct formatting.
Specify a valid stage ID from your pipeline; fallback to default pipeline if omitted.
Handle API errors (401, 403, 400, 429) with retries or reauthorization logic.

Example use cases

Create a minimal deal with name only for a new sales lead.
Create a full deal with amount, stage, and expected close date during handoff.
Automate deal creation from a form submission or inbound email parser.
Record a high-value opportunity quickly after a qualifying call.
Create placeholder deals in bulk from an onboarding CSV or script.

FAQ

What parameters are required?

Only the deal name is required. Amount, stage, closedate, and pipeline are optional.

What date format should I use for closedate?

Use YYYY-MM-DD (ISO date). The skill converts it to the HubSpot datetime format.

What if I get a 401 or 403 error?

401 means authentication failed — re-run the setup. 403 usually means missing crm.objects.deals.write scope.