# Pipedrive

Pipedrive is a customer relationship management (CRM) platform designed for sales teams. The Sling Pipedrive connector extracts data from the Pipedrive REST API, supporting deals, contacts (persons), organizations, activities, leads, products, and pipeline configuration data.

{% hint style="success" %}
**CLI Pro Required**: APIs require a [CLI Pro token](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform).
{% endhint %}

## Setup

The following credentials are accepted:

**Secrets:**

* `api_token` **(required)** -> Your Pipedrive API Token
* `domain` **(required)** -> Your Pipedrive company domain

**Inputs:**

* `anchor_date` (optional) -> The starting date for historical data extraction (default: 1 year ago). Format: `YYYY-MM-DD`

### Getting Your API Token and Domain

1. Log in to your [Pipedrive account](https://app.pipedrive.com/)
2. Go to **Settings** (gear icon in bottom left) > **Personal Preferences**
3. Go to the **API** tab
4. Copy your **API token** (a long alphanumeric string)
5. Your **domain** is the subdomain in your Pipedrive URL (e.g., if your URL is `https://mycompany.pipedrive.com`, your domain is `mycompany`)

{% hint style="warning" %}
**Important:** API tokens are tied to individual user accounts. If a user's account is deactivated, their API token will no longer work. Consider creating a dedicated service account for API integrations.
{% endhint %}

### Using `sling conns`

Here are examples of setting a connection named `PIPEDRIVE`. We must provide the `type=api` property:

{% code overflow="wrap" %}

```bash
sling conns set PIPEDRIVE type=api spec=pipedrive secrets='{ api_token: abc123def456, domain: mycompany }'
```

{% endcode %}

### Environment Variable

See [here](https://docs.slingdata.io/sling-cli/environment#dot-env-file-.env.sling) to learn more about the `.env.sling` file.

{% code overflow="wrap" %}

```bash
export PIPEDRIVE='{ type: api, spec: pipedrive, secrets: { api_token: "abc123def456", domain: "mycompany" } }'
```

{% endcode %}

### Sling Env File YAML

See [here](https://docs.slingdata.io/sling-cli/environment#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file.

```yaml
connections:
  PIPEDRIVE:
    type: api
    spec: pipedrive
    secrets:
      api_token: "abc123def456"
      domain: "mycompany"
```

**With anchor date for historical data:**

```yaml
connections:
  PIPEDRIVE:
    type: api
    spec: pipedrive
    secrets:
      api_token: "abc123def456"
      domain: "mycompany"
    inputs:
      anchor_date: "2020-01-01"
```

## Replication

Here's an example replication configuration to sync Pipedrive data to a PostgreSQL database:

```yaml
source: PIPEDRIVE
target: MY_POSTGRES

defaults:
  mode: incremental
  object: pipedrive.{stream_name}

streams:
  # Core CRM objects with incremental sync
  deals:
  persons:
  organizations:
  activities:
  leads:

  # Reference data (full-refresh only)
  pipelines:
    mode: full-refresh
  stages:
    mode: full-refresh
  users:
    mode: full-refresh
```

**Full refresh for reference data:**

```yaml
source: PIPEDRIVE
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: pipedrive.{stream_name}

streams:
  # Configuration and reference data
  pipelines:
  stages:
  users:
  products:
  activity_types:
  lead_labels:
  currencies:

  # Field definitions
  deal_fields:
  person_fields:
  organization_fields:
```

**Sync all endpoints:**

```yaml
source: PIPEDRIVE
target: MY_POSTGRES

defaults:
  mode: incremental
  object: pipedrive.{stream_name}

streams:
  # Sync all available endpoints
  '*':

  # Use full-refresh for reference data
  pipelines:
    mode: full-refresh
  stages:
    mode: full-refresh
  users:
    mode: full-refresh
  activity_types:
    mode: full-refresh
  lead_labels:
    mode: full-refresh
  currencies:
    mode: full-refresh
  deal_fields:
    mode: full-refresh
  person_fields:
    mode: full-refresh
  organization_fields:
    mode: full-refresh
  filters:
    mode: full-refresh
```

## Endpoints

### Core CRM Objects

| Endpoint        | Description                                         | Incremental |
| --------------- | --------------------------------------------------- | ----------- |
| `deals`         | Sales deals and opportunities                       | Yes         |
| `persons`       | Contact persons/individuals                         | Yes         |
| `organizations` | Companies and organizations                         | Yes         |
| `activities`    | Tasks, calls, meetings, and emails                  | Yes         |
| `leads`         | Sales leads                                         | Yes         |
| `notes`         | Notes attached to deals, persons, and organizations | Yes         |

### Products & Services

| Endpoint   | Description                   | Incremental |
| ---------- | ----------------------------- | ----------- |
| `products` | Products in your catalog      | Yes         |
| `files`    | File attachments and metadata | Yes         |

### Pipeline Configuration

| Endpoint    | Description     | Incremental |
| ----------- | --------------- | ----------- |
| `pipelines` | Sales pipelines | No          |
| `stages`    | Pipeline stages | No          |

### Users & Access

| Endpoint | Description                  | Incremental |
| -------- | ---------------------------- | ----------- |
| `users`  | Pipedrive users/team members | No          |

### Field Definitions

| Endpoint              | Description                                | Incremental |
| --------------------- | ------------------------------------------ | ----------- |
| `deal_fields`         | Custom field definitions for deals         | No          |
| `person_fields`       | Custom field definitions for persons       | No          |
| `organization_fields` | Custom field definitions for organizations | No          |

### Reference Data

| Endpoint         | Description                                           | Incremental |
| ---------------- | ----------------------------------------------------- | ----------- |
| `activity_types` | Activity type definitions (call, meeting, task, etc.) | No          |
| `lead_labels`    | Lead label/status definitions                         | No          |
| `filters`        | Saved filter definitions                              | No          |
| `currencies`     | Supported currencies for deals                        | No          |

To discover available endpoints:

```bash
sling conns discover PIPEDRIVE
```

## Incremental Sync

The Pipedrive connector uses time-based incremental sync for supported endpoints:

* **First run:** Fetches records modified from `anchor_date` (default: 1 year ago) to present
* **Subsequent runs:** Only fetches records modified after the last sync

Incremental sync is supported for core CRM objects:

* Deals
* Persons
* Organizations
* Activities
* Leads
* Notes
* Products
* Files

Reference data endpoints (pipelines, stages, users, activity\_types, lead\_labels, filters, currencies) do not support incremental sync and should be run in full-refresh mode.

### Update Tracking

Each endpoint tracks updates via:

* **update\_time** — Last modification timestamp (used for incremental sync)
* **add\_time** — Creation timestamp
* **owner\_id** — User ID of the record owner

## Rate Limiting

The Pipedrive API enforces rate limits based on your subscription plan:

* **Free plan:** 1 request per second
* **Paid plans:** 2 requests per second (or higher depending on plan)
* **Burst limit:** Up to 10 requests per second for short periods

The connector automatically:

* Uses conservative rate limiting (2 requests/second)
* Implements backoff on rate limit responses
* Retries with exponential backoff on 429 (rate limit) errors

## Common Use Cases

### Sync Core Sales Data

```yaml
source: PIPEDRIVE
target: MY_POSTGRES

defaults:
  mode: incremental
  object: sales.{stream_name}

streams:
  deals:
  persons:
  organizations:
  activities:
```

### Sync Leads Pipeline

```yaml
source: PIPEDRIVE
target: MY_POSTGRES

defaults:
  mode: incremental
  object: leads.{stream_name}

streams:
  leads:
  lead_labels:
    mode: full-refresh
  users:
    mode: full-refresh
```

### Sync Pipeline Configuration

```yaml
source: PIPEDRIVE
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: config.{stream_name}

streams:
  pipelines:
  stages:
  users:
```

### Full Data Export

```yaml
source: PIPEDRIVE
target: MY_POSTGRES

defaults:
  mode: incremental
  object: pipedrive.{stream_name}

streams:
  # Core CRM data
  deals:
  persons:
  organizations:
  activities:
  leads:
  notes:
  products:
  files:

  # Reference data
  pipelines:
    mode: full-refresh
  stages:
    mode: full-refresh
  users:
    mode: full-refresh
  deal_fields:
    mode: full-refresh
  person_fields:
    mode: full-refresh
  organization_fields:
    mode: full-refresh
  activity_types:
    mode: full-refresh
  lead_labels:
    mode: full-refresh
  currencies:
    mode: full-refresh
```

## Custom Fields

Pipedrive supports custom fields on deals, persons, and organizations. Custom field values are included in the base endpoint responses with keys like `[field_id]_value` or custom field names if configured.

The `*_fields` endpoints return metadata including field names, types (text, numeric, date, etc.), and whether they are required.

## Known Limitations

1. **Deleted records:** Pipedrive does not provide a way to fetch deleted records via the API. For full reconciliation, periodic full-refresh syncs are recommended.
2. **Large datasets:** If you have very large numbers of deals or persons (100K+), consider using the `anchor_date` input to backfill data gradually over time.
3. **Custom fields:** Custom field names and IDs are available in the `*_fields` endpoints, but the actual field structure may vary by workspace configuration.
4. **Associations:** Pipedrive does not expose a dedicated endpoint for deal-person or deal-organization relationships. These are managed through `linked_persons_ids` and `org_id` fields in the deals endpoint.

## Common Issues

**Issue:** "Authentication failed" or "Invalid API token"

* **Solution:** Verify the API token is correct and the associated user account is active. Check that your domain is correct (e.g., `mycompany` not `https://mycompany.pipedrive.com`).

**Issue:** "Custom field values are null"

* **Solution:** Custom fields are returned with numeric keys. Check the `deal_fields`, `person_fields`, or `organization_fields` endpoints to map field IDs to names.

**Issue:** "Rate limit errors (429 status)"

* **Solution:** The connector automatically retries with backoff. If errors persist, reduce the `concurrency` setting in your replication configuration or upgrade your Pipedrive plan for higher rate limits.

If you are facing issues connecting, please reach out to us at <support@slingdata.io>, on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.slingdata.io/connections/api-connections/pipedrive.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.