managing-pipedrive

name	managing-pipedrive
description	Use when working with Pipedrive — pipedrive CRM management including deals, persons, organizations, pipelines, activities, products, and email integration. Covers pipeline health, deal velocity, activity completion rates, revenue forecasting, and sales team performance.
connection_type	pipedrive
preload	false

Pipedrive Management Skill

Monitor and manage Pipedrive sales CRM and pipeline operations.

MANDATORY: Discovery-First Pattern

Always discover pipelines and users before querying deals or activities.

Phase 1: Discovery

#!/bin/bash
PD_API="https://api.pipedrive.com/v1"
TOKEN="api_token=${PIPEDRIVE_API_TOKEN}"

echo "=== Organization Info ==="
curl -s "$PD_API/users/me?$TOKEN" | \
  jq -r '.data | "User: \(.name)\nCompany: \(.company_name)\nRole: \(.role_key)\nTimezone: \(.timezone_name)"'

echo ""
echo "=== Pipelines ==="
curl -s "$PD_API/pipelines?$TOKEN" | \
  jq -r '.data[] | "\(.name) | ID: \(.id) | Active: \(.active) | Stages: \(.stages_count // "N/A") | Deals: \(.deals_count // "N/A")"'

echo ""
echo "=== Stages ==="
curl -s "$PD_API/stages?$TOKEN" | \
  jq -r '.data[] | "\(.name) | Pipeline: \(.pipeline_name) | Order: \(.order_nr) | Rotten Days: \(.rotten_days)"'

echo ""
echo "=== Users (Sales Team) ==="
curl -s "$PD_API/users?$TOKEN" | \
  jq -r '.data[] | "\(.name) | Email: \(.email) | Active: \(.active_flag) | Role: \(.role_key)"'

echo ""
echo "=== Custom Fields ==="
curl -s "$PD_API/dealFields?$TOKEN" | \
  jq -r '[.data[] | select(.is_subfield==false and .edit_flag==true)] | length | "Custom Deal Fields: \(.)"'

Phase 1 outputs: Company info, pipelines, stages, team, custom fields

Phase 2: Analysis

#!/bin/bash
echo "=== Deal Summary ==="
curl -s "$PD_API/deals/summary?$TOKEN&status=open" | \
  jq -r '.data | "Open Deals: \(.total_count)\nTotal Value: \(.total_currency_converted_value)\nAvg Value: \(.average_currency_converted_value)\nWeighted Value: \(.total_weighted_currency_converted_value)"'

echo ""
echo "=== Pipeline Distribution ==="
for pipeline_id in $(curl -s "$PD_API/pipelines?$TOKEN" | jq -r '.data[].id'); do
  name=$(curl -s "$PD_API/pipelines/$pipeline_id?$TOKEN" | jq -r '.data.name')
  summary=$(curl -s "$PD_API/deals/summary?$TOKEN&status=open&pipeline_id=$pipeline_id" | \
    jq -r '.data | "\(.total_count) deals, \(.total_currency_converted_value) value"')
  echo "$name: $summary"
done

echo ""
echo "=== Activities Due ==="
curl -s "$PD_API/activities?$TOKEN&type=all&done=0&limit=5" | \
  jq -r '.data[] | "\(.type) | \(.subject) | Due: \(.due_date) | Owner: \(.owner_name)"'

echo ""
echo "=== Won/Lost Ratio (last 30 days) ==="
won=$(curl -s "$PD_API/deals/summary?&status=won&start_date=" | jq )
lost=$(curl -s  | jq )
 

Output Format

PIPEDRIVE STATUS
================
Company: {name}
Pipelines: {count} | Users: {count}
Open Deals: {count} ({value})
30-Day Win Rate: {percent}%
Overdue Activities: {count}
Avg Deal Value: {amount}
Issues: {list_of_warnings}

Anti-Hallucination Rules

1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations

Shortcut	Counter	Why
"I'll skip discovery and check known resources"	Always run Phase 1 discovery first	Resource names change, new resources appear — assumed names cause errors
"The user only asked for a quick check"	Follow the full discovery → analysis flow	Quick checks miss critical issues; structured analysis catches silent failures
"Default configuration is probably fine"	Audit configuration explicitly	Defaults often leave logging, security, and optimization features disabled
"Metrics aren't needed for this"	Always check relevant metrics when available	API/CLI responses show current state; metrics reveal trends and intermittent issues
"I don't have access to that"	Try the command and report the actual error	Assumed permission failures prevent useful investigation; actual errors are informative

Common Pitfalls

• API token in URL: Pipedrive uses query param auth — ensure HTTPS always
• Rate limits: 100 requests per 10 seconds — batch where possible
• Currency conversion: Multi-currency orgs need converted values — use summary endpoints
• Rotten deals: Deals past rotten_days threshold are flagged — monitor stage aging