Pipedrive
by @byungkyu
Pipedrive API integration with managed OAuth. Manage deals, persons, organizations, activities, and pipelines. Use this skill when users want to interact wit...
clawhub install pipedrive-apiπ About This Skill
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
# List deals
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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://api.maton.ai/pipedrive/{native-api-path}
Maton 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:
export MATON_API_KEY="YOUR_API_KEY"
Getting Your API Key
1. Sign in or create an account at maton.ai 2. Go to maton.ai/settings 3. Copy your API key
Connection Management
Manage your Pipedrive OAuth connections at https://api.maton.ai.
List Connections
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'pipedrive'}).encode()
req = urllib.request.Request('https://api.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
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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:
{
"connection": {
"connection_id": "{connection_id}",
"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
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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:
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/pipedrive/api/v1/deals')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
If you have multiple connections, always include this header to ensure requests go to the intended account.
Security & Permissions
API Reference
Deals
#### List Deals
GET /pipedrive/api/v1/deals
Query parameters:
status - Filter by status: open, won, lost, deleted, all_not_deletedfilter_id - Filter ID to usestage_id - Filter by stageuser_id - Filter by userstart - Pagination start (default 0)limit - Items per page (default 100)sort - Sort field and order (e.g., add_time DESC)Example:
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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
GET /pipedrive/api/v1/deals/{id}
#### Create Deal
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
PUT /pipedrive/api/v1/deals/{id}
Content-Type: application/json{
"title": "Updated Deal Title",
"value": 75000,
"status": "won"
}
#### Delete Deal
DELETE /pipedrive/api/v1/deals/{id}
#### Search Deals
GET /pipedrive/api/v1/deals/search?term=enterprise
Persons (Contacts)
#### List Persons
GET /pipedrive/api/v1/persons
Query parameters:
filter_id - Filter IDstart - Pagination startlimit - Items per pagesort - Sort field and order#### Get Person
GET /pipedrive/api/v1/persons/{id}
#### Create Person
POST /pipedrive/api/v1/persons
Content-Type: application/json{
"name": "John Doe",
"email": ["john@example.com"],
"phone": ["+1234567890"],
"org_id": 456,
"visible_to": 3
}
#### Update Person
PUT /pipedrive/api/v1/persons/{id}
Content-Type: application/json{
"name": "John Smith",
"email": ["john.smith@example.com"]
}
#### Delete Person
DELETE /pipedrive/api/v1/persons/{id}
#### Search Persons
GET /pipedrive/api/v1/persons/search?term=john
Organizations
#### List Organizations
GET /pipedrive/api/v1/organizations
#### Get Organization
GET /pipedrive/api/v1/organizations/{id}
#### Create Organization
POST /pipedrive/api/v1/organizations
Content-Type: application/json{
"name": "Acme Corporation",
"address": "123 Main St, City, Country",
"visible_to": 3
}
#### Update Organization
PUT /pipedrive/api/v1/organizations/{id}
Content-Type: application/json{
"name": "Acme Corp International"
}
#### Delete Organization
DELETE /pipedrive/api/v1/organizations/{id}
Activities
#### List Activities
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 userstart_date - Filter by start dateend_date - Filter by end date#### Get Activity
GET /pipedrive/api/v1/activities/{id}
#### Create Activity
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
PUT /pipedrive/api/v1/activities/{id}
Content-Type: application/json{
"done": 1,
"note": "Completed - customer agreed to terms"
}
#### Delete Activity
DELETE /pipedrive/api/v1/activities/{id}
Pipelines
#### List Pipelines
GET /pipedrive/api/v1/pipelines
#### Get Pipeline
GET /pipedrive/api/v1/pipelines/{id}
Stages
#### List Stages
GET /pipedrive/api/v1/stages
Query parameters:
pipeline_id - Filter by pipeline#### Get Stage
GET /pipedrive/api/v1/stages/{id}
Notes
#### List Notes
GET /pipedrive/api/v1/notes
Query parameters:
deal_id - Filter by dealperson_id - Filter by personorg_id - Filter by organization#### Create Note
POST /pipedrive/api/v1/notes
Content-Type: application/json{
"content": "Meeting notes: Discussed pricing and timeline",
"deal_id": 789,
"pinned_to_deal_flag": 1
}
Users
#### List Users
GET /pipedrive/api/v1/users
#### Get Current User
GET /pipedrive/api/v1/users/me
Code Examples
JavaScript
const headers = {
'Authorization': Bearer ${process.env.MATON_API_KEY}
};// List open deals
const deals = await fetch(
'https://api.maton.ai/pipedrive/api/v1/deals?status=open',
{ headers }
).then(r => r.json());
// Create a deal
await fetch(
'https://api.maton.ai/pipedrive/api/v1/deals',
{
method: 'POST',
headers: { ...headers, 'Content-Type': 'application/json' },
body: JSON.stringify({
title: 'New Deal',
value: 10000,
currency: 'USD'
})
}
);
Python
import os
import requestsheaders = {'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
List open deals
deals = requests.get(
'https://api.maton.ai/pipedrive/api/v1/deals',
headers=headers,
params={'status': 'open'}
).json()Create a deal
response = requests.post(
'https://api.maton.ai/pipedrive/api/v1/deals',
headers=headers,
json={
'title': 'New Deal',
'value': 10000,
'currency': 'USD'
}
)
Notes
visible_to values: 1 (owner only), 3 (entire company), 5 (owner's visibility group), 7 (entire company and visibility group)open, won, lost, deletedstart and limit for paginationabc123_custom_field)curl -g when URLs contain brackets (fields[], sort[], records[]) to disable glob parsingjq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments. You may get "Invalid API key" errors when piping.Error Handling
| Status | Meaning | |--------|---------| | 400 | Missing Pipedrive connection | | 401 | Invalid or missing Maton API key | | 404 | Resource not found | | 429 | Rate limited (10 req/sec per account) | | 4xx/5xx | Passthrough error from Pipedrive API |
Troubleshooting: API Key Issues
1. Check that the MATON_API_KEY environment variable is set:
echo $MATON_API_KEY
2. Verify the API key is valid by listing connections:
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
Troubleshooting: Invalid App Name
1. Ensure your URL path starts with pipedrive. For example:
https://api.maton.ai/pipedrive/api/v1/dealshttps://api.maton.ai/api/v1/dealsResources
π‘ Examples
# List deals
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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
π Tips & Best Practices
#### List Notes
GET /pipedrive/api/v1/notes
Query parameters:
deal_id - Filter by dealperson_id - Filter by personorg_id - Filter by organization#### Create Note
POST /pipedrive/api/v1/notes
Content-Type: application/json{
"content": "Meeting notes: Discussed pricing and timeline",
"deal_id": 789,
"pinned_to_deal_flag": 1
}
Users
#### List Users
GET /pipedrive/api/v1/users
#### Get Current User
GET /pipedrive/api/v1/users/me