# Best Practices

## Recommended setup

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Start with Deals, Persons, and Organizations</strong></td><td>These three entities cover the core CRM data most sales teams need. Set up one data flow per entity, then use Coupler.io's data join to combine them (Deals → Persons via <code>person_id.value</code> = Persons <code>id</code>; Deals → Organizations via <code>org_id.value</code> = Organizations <code>id</code>).</td></tr><tr><td><strong>Use the Fields selector for focused exports</strong></td><td>Pipedrive returns many columns by default, especially with custom fields merged in. Select only the fields you need to keep your destination clean, speed up data flows, and avoid timeout issues on large accounts.</td></tr><tr><td><strong>Use sub-field names for linked records</strong></td><td>Pipedrive nests linked data in sub-fields. Use <code>owner_id.name</code> for the owner's name, <code>org_id.name</code> for the organization name, <code>stage_id.name</code> for the stage name. The raw <code>owner_id</code> field returns a nested object, not a plain value.</td></tr><tr><td><strong>Apply a Pipedrive filter for targeted exports</strong></td><td>Create filters directly in Pipedrive (e.g., "Open deals in Q1", "Active clients in Germany") and reference the filter ID in Coupler.io. This is the most reliable way to scope your export to a specific subset of records.</td></tr></tbody></table>

## Data refresh and scheduling

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Daily refresh for pipeline data</strong></td><td>Deals, Persons, and Organizations change frequently. A daily refresh (e.g., early morning) keeps your dashboards current without excessive API usage. For high-activity accounts, consider hourly refresh for Deals.</td></tr><tr><td><strong>Use date filters to limit the export window</strong></td><td>Set a <strong>Changed after</strong> date to pull only recently modified records and keep data flows fast. For ongoing reporting, update the date periodically or leave it empty for a full export on each run.</td></tr><tr><td><strong>Use "Replace" mode for standard exports</strong></td><td>Use "Replace" (overwrite) destination mode for most Pipedrive exports. This ensures your destination always reflects the current state of your CRM data. Only use "Append" if you're intentionally building a historical log.</td></tr><tr><td><strong>Stagger multiple data flows</strong></td><td>If you run several Pipedrive data flows (e.g., Deals + Persons + Organizations), stagger their schedules by a few minutes. This avoids hitting Pipedrive's rate limit (20 requests per 2 seconds on entry-level plans) across concurrent flows.</td></tr></tbody></table>

## Performance optimization

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Filter before you export</strong></td><td>Use Pipedrive filters and date ranges to reduce the dataset at the API level. Pulling a focused subset is much faster than exporting everything and filtering in your destination. A filter-scoped export also reduces the chance of timeouts on large accounts.</td></tr><tr><td><strong>Limit columns on the Deals entity</strong></td><td>Deals exports include many columns by default — standard fields, custom fields, and nested sub-fields. Explicitly specifying 15–20 key columns in the Fields selector can cut execution time significantly.</td></tr><tr><td><strong>Use standard Deals, not All deals (BETA), for regular reporting</strong></td><td>The All deals (BETA) entity uses cursor-based pagination for very large datasets and requires global admin access. For most use cases, the standard Deals entity with a date filter or a Pipedrive filter is faster and more accessible.</td></tr><tr><td><strong>Combine entities with data join, not multiple fields in one flow</strong></td><td>Do not try to replicate Persons or Organizations data within the Deals export by over-selecting fields. Instead, set up a separate data flow for each entity and join them using Coupler.io's data join. This keeps each flow lean and easier to maintain.</td></tr></tbody></table>

## Dashboard accuracy

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Joining entities via person and organization IDs</strong></td><td>To enrich Deals with contact or account details, join Deals to Persons using <code>person_id.value</code> (from Deals) = <code>id</code> (from Persons). For organizations, join on <code>org_id.value</code> = <code>id</code> from Organizations. Include these ID fields in your Fields selector to ensure they appear in the export.</td></tr><tr><td><strong>Include both ID and name sub-fields when needed for joins</strong></td><td>If your dashboard requires both the ID (for joining) and the name (for display) of a linked field, include both sub-fields explicitly: e.g., <code>person_id.value</code> and <code>person_id.name</code>, or <code>org_id.value</code> and <code>org_id.name</code>.</td></tr><tr><td><strong>Account for active-only data from the API</strong></td><td>By default, the Pipedrive API returns active records only. Deleted or archived deals, persons, and organizations are not included. If your dashboard needs to account for churn or closed accounts, note that historical records may not be present.</td></tr><tr><td><strong>Use Pipedrive filters for pipeline-scoped dashboards</strong></td><td>If you maintain multiple pipelines in Pipedrive (e.g., New Business vs. Renewals), create a separate Pipedrive filter for each and set up a dedicated Coupler.io data flow per pipeline. This keeps your data flows modular and your dashboards clearly scoped.</td></tr></tbody></table>

## Combining Pipedrive entities

Each Coupler.io data flow exports one Pipedrive entity. To combine data from multiple entities — for example, enriching Deals with person and organization details — set up a separate data flow for each entity and use Coupler.io's data join.

#### Example: Deals enriched with Persons and Organizations

**Data flow 1 — Deals**

Fields to include:

```
title
value
status
stage_id.name
pipeline_id.name
owner_id.name
person_id.value
person_id.name
org_id.value
org_id.name
add_time
close_time
```

**Data flow 2 — Persons**

Fields to include:

```
id
name
email
phone
org_id.name
```

**Data flow 3 — Organizations** *(optional, for additional account detail)*

Fields to include:

```
id
name
address
owner_id.name
```

**Joining the data**

* Join Deals → Persons: match `person_id.value` (from Deals) with `id` (from Persons)
* Join Deals → Organizations: match `org_id.value` (from Deals) with `id` (from Organizations)

{% hint style="info" %}
Always include the ID sub-field (e.g., `person_id.value`, `org_id.value`) in your Deals data flow — this is the key used to join with the corresponding entity's `id` column. Without it, the join has nothing to match on.
{% endhint %}

#### Join keys by entity pair

| Combine               | Join key in Deals | Join key in other entity |
| --------------------- | ----------------- | ------------------------ |
| Deals + Persons       | `person_id.value` | Persons `id`             |
| Deals + Organizations | `org_id.value`    | Organizations `id`       |
| Leads + Persons       | `person_id.value` | Persons `id`             |
| Leads + Organizations | `org_id.value`    | Organizations `id`       |

## Common pitfalls to avoid

{% columns %}
{% column %}
**Do**

* Use `owner_id.name`, `stage_id.name`, `org_id.name` sub-fields for human-readable labels
* Create Pipedrive filters for targeted, reliable scoping
* Run once with no Fields specified to discover available columns before refining
* Use the date picker to set a **Changed after** date and limit exports to recently modified records
* Stagger multiple data flow schedules to avoid rate limit issues
  {% endcolumn %}

{% column %}
**Don't**

* Don't try to combine multiple Pipedrive entities in a single data flow — use data join instead
* Don't use the All deals (BETA) entity unless you have Pipedrive global admin access and a specific need for cursor-based pagination
* Don't use "Append" mode for standard CRM exports — it accumulates duplicate rows over time
* Don't rely on Pipedrive's in-app analytics reports being available via API — only raw CRM records are accessible
* Don't expect Activities, Files, or Call logs to include custom fields — custom field merging applies only to Deals, Persons, Organizations, Leads, and Products
  {% endcolumn %}
  {% endcolumns %}

{% hint style="danger" %}
**Pipedrive in-app reports and analytics are not available via the API.** Coupler.io exports raw CRM records only. Forecasts, revenue projections, and built-in Pipedrive reports must be recreated using your destination tool (Google Sheets, Looker Studio, Power BI, etc.) with the raw data exported by Coupler.io.
{% endhint %}