pipedrive

# 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": ["john@example.com"],
  "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": ["john.smith@example.com"]
}
```

#### 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 Stages

```bash
GET /pipedrive/api/v1/stages
```

Query parameters:
- `pipeline_id` - Filter by pipeline

#### Get Stage

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

### Notes

#### List Notes

```bash
GET /pipedrive/api/v1/notes
```

Query parameters:
- `deal_id` - Filter by deal
- `person_id` - Filter by person
- `org_id` - Filter by organization

#### Create Note

```bash
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

```bash
GET /pipedrive/api/v1/users
```

#### Get Current User

```bash
GET /pipedrive/api/v1/users/me
```

## Code Examples

### JavaScript

```javascript
const headers = {
  'Authorization': `Bearer ${process.env.MATON_API_KEY}`
};

// List open deals
const deals = await fetch(
  'https://gateway.maton.ai/pipedrive/api/v1/deals?status=open',
  { headers }
).then(r => r.json());

// Create a deal
await fetch(
  'https://gateway.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

```python
import os
import requests

headers = {'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}

# List open deals
deals = requests.get(
    'https://gateway.maton.ai/pipedrive/api/v1/deals',
    headers=headers,
    params={'status': 'open'}
).json()

# Create a deal
response = requests.post(
    'https://gateway.maton.ai/pipedrive/api/v1/deals',
    headers=headers,
    json={
        'title': 'New Deal',
        'value': 10000,
        'currency': 'USD'
    }
)
```

## Notes

- IDs are integers
- Email and phone fields accept arrays for multiple values
- `visible_to` values: 1 (owner only), 3 (entire company), 5 (owner's visibility group), 7 (entire company and visibility group)
- Deal status: `open`, `won`, `lost`, `deleted`
- Use `start` and `limit` for pagination
- Custom fields are supported via their API key (e.g., `abc123_custom_field`)
- IMPORTANT: When using curl commands, use `curl -g` when URLs contain brackets (`fields[]`, `sort[]`, `records[]`) to disable glob parsing
- IMPORTANT: When piping curl output to `jq` 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: Invalid API Key

**When you receive a "Invalid API key" error, ALWAYS follow these steps before concluding there is an issue:**

1. Check that the `MATON_API_KEY` environment variable is set:

```bash
echo $MATON_API_KEY
```

2. Verify the API key is valid by listing connections:

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.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
```

## Resources

- [Pipedrive API Overview](https://developers.pipedrive.com/docs/api/v1)
- [Deals](https://developers.pipedrive.com/docs/api/v1/Deals)
- [Persons](https://developers.pipedrive.com/docs/api/v1/Persons)
- [Organizations](https://developers.pipedrive.com/docs/api/v1/Organizations)
- [Activities](https://developers.pipedrive.com/docs/api/v1/Activities)
- [Pipelines](https://developers.pipedrive.com/docs/api/v1/Pipelines)
- [Stages](https://developers.pipedrive.com/docs/api/v1/Stages)
- [Notes](https://developers.pipedrive.com/docs/api/v1/Notes)