Pipedrive

---
name: pipedrive
description: |
  Pipedrive API integration with managed OAuth. Manage deals, persons, organizations, activities, and pipelines. Use this skill when users want to interact with Pipedrive CRM. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
compatibility: Requires network access and valid Maton API key
metadata:
  author: maton
  version: "1.0"
  clawdbot:
    emoji: 🧠
    requires:
      env:
        - MATON_API_KEY
---

# Pipedrive

Access the Pipedrive API with managed OAuth authentication. Manage deals, persons, organizations, activities, pipelines, and more for sales CRM workflows.

## Quick Start

```bash
# List deals
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/pipedrive/api/v1/deals')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

## Base URL

```
https://gateway.maton.ai/pipedrive/{native-api-path}
```

Replace `{native-api-path}` with the actual Pipedrive API endpoint path. The gateway proxies requests to `api.pipedrive.com` and automatically injects your OAuth token.

## Authentication

All requests require the Maton API key in the Authorization header:

```
Authorization: Bearer $MATON_API_KEY
```

**Environment Variable:** Set your API key as `MATON_API_KEY`:

```bash
export MATON_API_KEY="YOUR_API_KEY"
```

### Getting Your API Key

1. Sign in or create an account at [maton.ai](https://maton.ai)
2. Go to [maton.ai/settings](https://maton.ai/settings)
3. Copy your API key

## Connection Management

Manage your Pipedrive OAuth connections at `https://ctrl.maton.ai`.

### List Connections

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=pipedrive&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

### Create Connection

```bash
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'pipedrive'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

### Get Connection

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

**Response:**
```json
{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "pipedrive",
    "metadata": {}
  }
}
```

Open the returned `url` in a browser to complete OAuth authorization.

### Delete Connection

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

### Specifying Connection

If you have multiple Pipedrive connections, specify which one to use with the `Maton-Connection` header:

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/pipedrive/api/v1/deals')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

If omitted, the gateway uses the default (oldest) active connection.

## API Reference

### Deals

#### List Deals

```bash
GET /pipedrive/api/v1/deals
```

Query parameters:
- `status` - Filter by status: `open`, `won`, `lost`, `deleted`, `all_not_deleted`
- `filter_id` - Filter ID to use
- `stage_id` - Filter by stage
- `user_id` - Filter by user
- `start` - Pagination start (default 0)
- `limit` - Items per page (default 100)
- `sort` - Sort field and order (e.g., `add_time DESC`)

**Example:**

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/pipedrive/api/v1/deals?status=open&limit=50')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

#### Get Deal

```bash
GET /pipedrive/api/v1/deals/{id}
```

#### Create Deal

```bash
POST /pipedrive/api/v1/deals
Content-Type: application/json

{
  "title": "New Enterprise Deal",
  "value": 50000,
  "currency": "USD",
  "person_id": 123,
  "org_id": 456,
  "stage_id": 1,
  "expected_close_date": "2025-06-30"
}
```

#### Update Deal

```bash
PUT /pipedrive/api/v1/deals/{id}
Content-Type: application/json

{
  "title": "Updated Deal Title",
  "value": 75000,
  "status": "won"
}
```

#### Delete Deal

```bash
DELETE /pipedrive/api/v1/deals/{id}
```

#### Search Deals

```bash
GET /pipedrive/api/v1/deals/search?term=enterprise
```

### Persons (Contacts)

#### List Persons

```bash
GET /pipedrive/api/v1/persons
```

Query parameters:
- `filter_id` - Filter ID
- `start` - Pagination start
- `limit` - Items per page
- `sort` - Sort field and order

#### Get Person

```bash
GET /pipedrive/api/v1/persons/{id}
```

#### Create Person

```bash
POST /pipedrive/api/v1/persons
Content-Type: application/json

{
  "name": "John Doe",
  "email": ["[email protected]"],
  "phone": ["+1234567890"],
  "org_id": 456,
  "visible_to": 3
}
```

#### Update Person

```bash
PUT /pipedrive/api/v1/persons/{id}
Content-Type: application/json

{
  "name": "John Smith",
  "email": ["[email protected]"]
}
```

#### Delete Person

```bash
DELETE /pipedrive/api/v1/persons/{id}
```

#### Search Persons

```bash
GET /pipedrive/api/v1/persons/search?term=john
```

### Organizations

#### List Organizations

```bash
GET /pipedrive/api/v1/organizations
```

#### Get Organization

```bash
GET /pipedrive/api/v1/organizations/{id}
```

#### Create Organization

```bash
POST /pipedrive/api/v1/organizations
Content-Type: application/json

{
  "name": "Acme Corporation",
  "address": "123 Main St, City, Country",
  "visible_to": 3
}
```

#### Update Organization

```bash
PUT /pipedrive/api/v1/organizations/{id}
Content-Type: application/json

{
  "name": "Acme Corp International"
}
```

#### Delete Organization

```bash
DELETE /pipedrive/api/v1/organizations/{id}
```

### Activities

#### List Activities

```bash
GET /pipedrive/api/v1/activities
```

Query parameters:
- `type` - Activity type (e.g., `call`, `meeting`, `task`, `email`)
- `done` - Filter by completion (0 or 1)
- `user_id` - Filter by user
- `start_date` - Filter by start date
- `end_date` - Filter by end date

#### Get Activity

```bash
GET /pipedrive/api/v1/activities/{id}
```

#### Create Activity

```bash
POST /pipedrive/api/v1/activities
Content-Type: application/json

{
  "subject": "Follow-up call",
  "type": "call",
  "due_date": "2025-03-15",
  "due_time": "14:00",
  "duration": "00:30",
  "deal_id": 789,
  "person_id": 123,
  "note": "Discuss contract terms"
}
```

#### Update Activity

```bash
PUT /pipedrive/api/v1/activities/{id}
Content-Type: application/json

{
  "done": 1,
  "note": "Completed - customer agreed to terms"
}
```

#### Delete Activity

```bash
DELETE /pipedrive/api/v1/activities/{id}
```

### Pipelines

#### List Pipelines

```bash
GET /pipedrive/api/v1/pipelines
```

#### Get Pipeline

```bash
GET /pipedrive/api/v1/pipelines/{id}
```

### Stages

#### List S