> ## Documentation Index
> Fetch the complete documentation index at: https://www.integrate.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ETL: Pipedrive Source

> Configure the Pipedrive source in Integrate.io ETL to read deals, persons, organizations, activities, products, and pipelines with an API token.

Use the Pipedrive source component to read data from your Pipedrive sales CRM into your [Integrate.io](http://integrate.io/) ETL pipeline. The connector reads 13 Pipedrive objects, including deals, persons, organizations, activities, and products. Six objects support incremental loads on their update time.

Use this component instead of building a [REST API source](https://www.integrate.io/docs/etl/using-components-rest-api-source.md) with the API token in the URL. The native connector handles authentication, pagination, rate limits, and custom field names for you.

## Prerequisites

* A Pipedrive account.
* A personal API token, found in Pipedrive under **Settings → Personal preferences → API**.

The connection reads data with the visibility of the user who owns the token. Records hidden from that user are not returned.

## Connection setup

**Step 1**

Go to **Connections → New connection → Pipedrive**.

**Step 2**

Enter a **Name** and paste your **API Token**. The fields are described below.

**Step 3**

Click **Test connection**. The test reads the Pipedrive user that owns the token.

**Step 4**

Click **Create Connection**.

| Field | Description |
| :- | :- |
| Name | Display name for the connection inside Integrate.io. |
| API Token | Your Pipedrive personal API token. Integrate.io sends it in the `x-api-token` header to `api.pipedrive.com`, so no company domain is needed. |

![New Pipedrive connection form with the Name and API Token fields](https://mintcdn.com/integrateio/Z8nd36rCVoEVoKof/images/creating-packages/using-components-pipedrive-source/image-1.png?fit=max\&auto=format\&n=Z8nd36rCVoEVoKof\&q=85\&s=31d7d9ea03683daf26a670bae473a893)

> [!NOTE]
>
> Pipedrive OAuth connections are no longer offered for new connections. Existing ones still load and appear as **Pipedrive (OAuth, legacy)**. Create a Pipedrive API token connection to use the Pipedrive source component.

You can also select a Pipedrive connection in the [REST API source](https://www.integrate.io/docs/etl/using-components-rest-api-source.md) and [REST API destination](https://www.integrate.io/docs/etl/using-components-rest-api-destination.md) to call Pipedrive endpoints that this component does not read. Integrate.io sends the token in the `x-api-token` header for those components too.

## Source properties

The source component is configured in Step 02 of the component editor.

### Source table (object)

Select the Pipedrive object to read data from:

| Object | Pipedrive endpoint | Incremental load |
| - | - | - |
| deals | `/v2/deals` | Supported |
| archived\_deals | `/v2/deals/archived` | Supported |
| persons | `/v2/persons` | Supported |
| organizations | `/v2/organizations` | Supported |
| activities | `/v2/activities` | Supported |
| products | `/v2/products` | Supported (newer than only) |
| pipelines | `/v2/pipelines` | Not supported |
| stages | `/v2/stages` | Not supported |
| deal\_fields | `/v2/dealFields` | Not supported |
| person\_fields | `/v2/personFields` | Not supported |
| organization\_fields | `/v2/organizationFields` | Not supported |
| product\_fields | `/v2/productFields` | Not supported |
| activity\_fields | `/v2/activityFields` | Not supported |

The `deals` object does not include archived deals. Load `archived_deals` to read them. Each `archived_deals` request uses twice as much of your daily Pipedrive API budget as a `deals` request.

The `*_fields` objects return the definitions of your Pipedrive fields, including custom field names and their options. Use them to look up custom field keys and option IDs.

Integrate.io reads 500 records per page and stops after 10,000 pages, which is 5 million records per object. The job does not fail when it reaches that limit, so load larger histories in incremental windows.

### Load type

Select how records are loaded on each pipeline run:

* **Full Load.** Fetches all records for the selected object on every run.
* **Incremental Load.** Fetches only records updated before or after a reference date. Not available for `pipelines`, `stages`, and the `*_fields` objects, because Pipedrive's endpoints for them don't accept an update time filter.

### Incremental load settings

When **Incremental Load** is selected, the following options appear:

| Field | Description |
| :- | :- |
| Sync date field | Only `update_time` is offered. Pipedrive filters list endpoints by update time only. |
| Load records | `newer than ( > )` or `older than ( < )` the reference date. For `products`, only `newer than ( > )` is available, because Pipedrive has no "updated until" filter for products. |
| Reference date | **Last successful run** loads records since the last successful run of this pipeline, using the `$_PACKAGE_LAST_SUCCESSFUL_JOB_SUBMISSION_TIMESTAMP` system variable. Recommended for scheduled pipelines. **Fixed Date** sends a date such as `2026-10-01` to Pipedrive as `2026-10-01T00:00:00Z` (midnight UTC). **Variable** uses a custom package variable. |

![Pipedrive source properties with the deals object and an incremental load on update\_time since the last successful run](https://mintcdn.com/integrateio/Z8nd36rCVoEVoKof/images/creating-packages/using-components-pipedrive-source/image-2.png?fit=max\&auto=format\&n=Z8nd36rCVoEVoKof\&q=85\&s=98d161be418eb8e275111813eae57aea)

For example, an incremental load of deals newer than October 1, 2026 filters the request like this:

```text theme={null}
GET https://api.pipedrive.com/api/v2/deals?include_option_labels=true&updated_since=2026-10-01T00:00:00Z&limit=500
```

Pipedrive filters by the second. `newer than ( > )` also returns records updated in the same second as the reference date, so a record can be loaded twice across runs. Use a merge or upsert in your destination to avoid duplicates. `older than ( < )` leaves out records updated in that second.

### Rate limits

Pipedrive limits each API token to 20 requests per 2 seconds, shared with your other Pipedrive integrations. Integrate.io sends at most 8 requests per second. When Pipedrive returns HTTP 429, Integrate.io retries the request up to eight times with increasing backoff.

## Source schema

After configuring the source properties, the **Schema** section (Step 03) displays the available fields with their detected data types. Use the field selector to choose which columns to include in your pipeline. You can rename fields with aliases and change data types as needed.

Nested JSON objects in Pipedrive responses are flattened into individual columns with underscore-separated names.

### Custom fields

Pipedrive returns custom fields keyed by a 40-character hash, so each one becomes a column such as `custom_fields_843a...`. For `deals`, `archived_deals`, `persons`, `organizations`, `products`, and `activities`, Integrate.io looks up the name you gave the field in Pipedrive and uses it as the default alias. For example, a custom field named "Deal source" gets the alias `deal_source`.

* An alias that matches a standard column gets a `cf_` prefix, such as `cf_status`.
* Custom fields with the same name get a numeric suffix, such as `region` and `region_2`.
* A field whose name has no Latin letters or digits keeps its hash column name.

The pipeline reads the hash column, which never changes. Renaming a custom field in Pipedrive does not break an existing pipeline. Integrate.io caches field names for 15 minutes, so a rename shows up in the schema after that.

For `deals`, `persons`, and `organizations`, single and multiple option custom fields contain JSON with the option ID and label, such as `{"id": 41, "label": "Enterprise"}`. Other objects, including `archived_deals`, return the option ID only. Load the matching `*_fields` object to map option IDs to labels.

![Select input fields step with the deal\_source alias on a custom field and an option label in the data preview](https://mintcdn.com/integrateio/Z8nd36rCVoEVoKof/images/creating-packages/using-components-pipedrive-source/image-3.png?fit=max\&auto=format\&n=Z8nd36rCVoEVoKof\&q=85\&s=d43a6bc4ca8dde261251ad6ae6aa1cc4)

## FAQ

**Q: Why are some deals missing?**

The `deals` object does not return archived deals. Add a second source that loads `archived_deals`. The connection also reads only the records that the token's Pipedrive user can see.

**Q: Can I load products incrementally with `older than ( < )`?**

No. Pipedrive's products endpoint has no "updated until" filter, so only `newer than ( > )` is offered, and package validation rejects any other direction.

**Q: Does renaming a custom field in Pipedrive break my pipeline?**

No. The pipeline reads the custom field's hash column, which never changes. Only the default alias that the schema step suggests changes.

## Related

> [card] [REST API Source](https://www.integrate.io/docs/etl/using-components-rest-api-source.md)

> [card] [REST API Destination](https://www.integrate.io/docs/etl/using-components-rest-api-destination.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.