Skip to main content

Pipedrive

Availability
Available CoreAvailable StandardAvailable PlusAvailable ProAvailable Enterprise FlexAvailable PyAirbyte
Support Level
Marketplace
Connector Version
3.0.1 (last updated 5 days ago)
Sync Success Rate
Medium
Usage Rate
High
Data workers used
0.2 per sync (Learn more)
Definition ID
d8286229-c680-4063-8c59-23b9b391c700

This page contains the setup guide and reference information for the Pipedrive source connector.

Prerequisites​

  • A Pipedrive account with API access enabled for your user
  • Your Pipedrive API Token

Setup guide​

Step 1: Set up Pipedrive​

The connector authenticates with a personal API token. Each token is tied to a Pipedrive user, so the connector can only read data that user is allowed to see.

  1. In the Pipedrive web app, click your account name (top right), then Company settings > Personal preferences > API.
  2. Copy the API token shown on that page. See How to find the API token for screenshots.

Pipedrive allows one active API token per user. If you regenerate it, update the connector configuration. If you belong to more than one company, each company has its own token.

If the API tab isn't visible, your company admin hasn't enabled API access for your permission set. Ask them to follow Enabling API for company users.

Step 2: Set up the Pipedrive connector in Airbyte​

  1. In the Airbyte UI, go to Sources and click + New source.
  2. Select Pipedrive from the list.
  3. Enter a name for the source.
  4. Fill in the fields below, then click Set up source.

API Token: The personal API token you copied in Step 1. Airbyte sends it as the api_token query parameter on every request.

Start Date (optional): A UTC date and time in the format YYYY-MM-DDTHH:MM:SSZ, for example 2017-01-25T00:00:00Z. Defaults to 2010-01-01T00:00:00Z when left empty. The API v2 streams, notes and leads send it to Pipedrive as an inclusive updated_since filter; files and deal_flow read their full lists and keep the records modified on or after it. Streams that don't support incremental sync ignore it and always return all records, except deal_products and deal_installments, which only expand the deals returned by deals and deals_archived. A space instead of T, as in the example shown in the UI, also works. See Incremental sync and Start Date.

Number of concurrent workers (optional): How many streams Airbyte syncs in parallel, from 1 to 10. Defaults to 3. All requests share one client-side request budget sized to Pipedrive's lowest-plan burst limit, so higher values rarely make a sync faster.

When you click Set up source, Airbyte tests the connection by calling the Currencies endpoint. Every API token can read it, so the test passes even on an account that has no deals yet.

Supported sync modes​

The Pipedrive source connector supports the following sync modes:

FeatureSupported?
Full Refresh SyncYes
Incremental SyncYes
Replicate Incremental DeletesYes (deals and deals_archived only)
SSL connectionYes
NamespacesNo

Supported Streams​

Most streams read Pipedrive API v1; deals, deals_archived, persons, organizations, activities, products, pipelines, stages, deal_products, deal_installments, projects and tasks read API v2. Ten streams support incremental sync: deals, deals_archived, persons, organizations, activities, products, notes and leads filter on the server with updated_since, while files and deal_flow filter client-side. The other twenty-five streams are full refresh only. Stream names below match the names shown in Airbyte.

StreamSync modesNotes
activitiesFull Refresh, IncrementalAPI v2 api/v2/activities, cursor: update_time.
activity_fieldsFull RefreshActivityFields
activity_typesFull RefreshActivityTypes
call_logsFull RefreshCall logs of the token's user (CallLogs). Empty unless a phone integration is connected in Pipedrive.
currenciesFull RefreshCurrencies
deal_fieldsFull RefreshDealFields
deal_flowFull Refresh, IncrementalField change history of each deal returned by deals and deals_archived (Deals getDealUpdates), one request per deal, so it is slow on large accounts. Cursor: log_time, filtered client-side.
deal_installmentsFull RefreshPayment installments of deals returned by deals and deals_archived (DealInstallments), 100 deals per request. Installments are only available on Pipedrive's Growth plan and higher; the stream is empty on other plans.
deal_productsFull RefreshProducts attached to each deal, fetched with one request per deal from API v2 GET /api/v2/deals/{id}/products. Expands the deals returned by deals and deals_archived.
dealsFull Refresh, IncrementalNot-archived deals from API v2 GET /api/v2/deals with status=open,won,lost,deleted, so deals deleted within the last 30 days are included with is_deleted: true. Cursor: update_time.
deals_archivedFull Refresh, IncrementalArchived deals from API v2 GET /api/v2/deals/archived, same fields and status handling as deals. Cursor: update_time.
filesFull Refresh, IncrementalAPI v1 GET /v1/files sorted by update_time; the connector reads the full list and keeps records modified on or after the cursor. Cursor: update_time.
filtersFull RefreshAPI v1 /filters.
goalsFull RefreshGoals
lead_labelsFull RefreshLeadLabels
lead_sourcesFull RefreshLeadSources
leadsFull Refresh, IncrementalLeads with the inclusive updated_since filter, sorted by update_time. Cursor: update_time.
legacy_teamsFull RefreshLegacyTeams. Pipedrive has deprecated this endpoint; the stream is empty when the Teams feature is disabled for your company or the endpoint has been retired.
mailFull RefreshMessages in each mail thread, fetched with one request per thread (Mailbox getMailThreadMessages). See Mail streams.
mailThreadsFull RefreshMail threads from the inbox, drafts, sent, and archive folders (Mailbox getMailThreads). See Mail streams.
notesFull Refresh, IncrementalAPI v1 GET /v1/notes with the inclusive updated_since filter. Cursor: update_time.
organization_fieldsFull RefreshOrganizationFields
organizationsFull Refresh, IncrementalAPI v2 api/v2/organizations, cursor: update_time.
permission_set_assignmentsFull RefreshUsers assigned to each permission set (PermissionSets). Requires an admin API token; the stream is empty otherwise.
permission_setsFull RefreshPermissionSets
person_fieldsFull RefreshPersonFields
personsFull Refresh, IncrementalAPI v2 api/v2/persons, cursor: update_time.
pipelinesFull RefreshAPI v2 api/v2/pipelines.
product_fieldsFull RefreshProductFields
productsFull Refresh, IncrementalAPI v2 api/v2/products, cursor: update_time.
projectsFull RefreshActive and archived projects (Projects). Requires the Projects add-on; the stream is empty otherwise.
rolesFull RefreshRoles
stagesFull RefreshAPI v2 api/v2/stages.
tasksFull RefreshProject tasks (Tasks). Requires the Projects add-on; the stream is empty otherwise. Pipedrive marks the Tasks API as beta.
usersFull RefreshAPI v1 /users.

Incremental sync and Start Date​

deals, deals_archived, persons, organizations, activities, products, notes and leads send the Start Date, or the last saved cursor, to Pipedrive as the updated_since parameter. The filter is inclusive, so every incremental run re-emits the record whose update_time equals the saved cursor; destinations deduplicate it on the primary key. files reads the full list sorted by update_time and keeps the records modified on or after the cursor; deal_flow does the same with each deal's change history on log_time. pipelines, stages, filters and users are full refresh: the v2 pipelines and stages endpoints have no updated_since parameter, and the v1 filters and users endpoints return short unpaginated lists.

deals and deals_archived request status=open,won,lost,deleted, so deals deleted within the last 30 days are returned with is_deleted: true. No other stream requests deleted records; the is_deleted field on other API v2 records and on users is passed through as Pipedrive returns it. Archived deals are delivered by deals_archived and carry is_archived: true.

Custom fields​

Pipedrive lets you add custom fields to deals, persons, organizations, products, and activities. The API returns each custom field as a 40-character hash key rather than a readable name. API v2 streams expose these values under the custom_fields object. To map a hash key to its label and type, sync the matching *_fields stream (deal_fields, person_fields, organization_fields, product_fields, or activity_fields) and join on the key column.

Monetary custom fields are objects with value and currency keys instead of the separate <hash> and <hash>_currency fields that API v1 returned.

Mail streams​

mailThreads lists threads from the mailbox of the user who owns the API token. It queries each of the inbox, drafts, sent, and archive folders separately, so a thread that appears in more than one folder may be returned more than once. mail then requests the messages of every thread returned by mailThreads, one request per thread. Both streams are full refresh only, and you only see mail for the user whose token you configured, not for the whole company. If that user has not connected a mailbox to Pipedrive (Mail sync), both streams return no records.

Performance considerations​

Pipedrive enforces per-company, token-based rate limits that depend on your plan and the number of seats. The connector throttles itself to 20 requests per rolling 2 seconds across all streams, the burst limit of Pipedrive's lowest plan, so bursts rarely trigger a 429 no matter how many workers you configure. When Pipedrive answers with HTTP 429, the connector waits for the window reported in the x-ratelimit-reset header, falls back to exponential backoff when the header is missing, and retries up to ten times before failing the sync. If the header asks for a wait of 300 seconds or more, the connector stops the sync with a retryable error instead of waiting. Two limits apply per API token: a rolling 2-second burst window (20 to 120 requests depending on your plan) that recovers after a short wait, and a daily token budget (30,000 tokens times the plan multiplier and the number of seats) that, once exhausted, rejects every request until midnight in Pipedrive's server timezone. Waiting does not help in the second case; the failure message says so. If your account is close to its limits, run fewer streams per connection or schedule syncs less often.

Four streams make requests per parent record and can be slow on large accounts:

  • deal_products makes one request per deal.
  • mail makes one request per mail thread.
  • deal_flow makes one request per deal returned by deals and deals_archived.
  • deal_installments makes one request per 100 deals returned by deals and deals_archived.

Consider leaving these streams disabled unless you need them.

Limitations & Troubleshooting​

Expand to see details about Pipedrive connector limitations and troubleshooting.

Connector limitations​

How the connector treats Pipedrive HTTP errors:

HTTP statusBehavior
401, 402, 403The sync fails with a configuration error that includes Pipedrive's error text. For deal_products, deal_flow and mail, a 403 on a single parent record is skipped and the sync continues. If the token can't read any deal products, deal changes or mail messages at all, those three streams finish empty rather than failing. projects, tasks and deal_installments treat a 402 or 403 on the whole endpoint, and legacy_teams and permission_set_assignments a 403, as a feature that isn't available on the account or to the token's user, and return no records instead of failing.
404, 410For deal_products, deal_flow and mail, a parent deal or mail thread deleted after the parent stream was read is skipped. legacy_teams returns no records on 404 or 410, and projects and tasks on 404. On other streams these fail the sync.
429Rate limited; retried as described under Performance considerations.
500, 502, 503, 504Temporary Pipedrive errors; retried with backoff.
  • Deletions are replicated for deals and deals_archived only, and only for 30 days after the deletion (is_deleted: true). Records deleted in other streams stay in your destination until you clear and resync the stream.
  • Ten streams track state: deals, deals_archived, persons, organizations, activities, products, notes, leads, files and deal_flow. The other twenty-five are re-read in full on every sync.
  • Full refresh streams ignore the Start Date, except deal_products and deal_installments, which only expand the deals returned by deals and deals_archived.
  • The connector authenticates with a personal API token only. It doesn't support OAuth.
  • deals, deals_archived, persons, organizations, activities, products, pipelines, stages, deal_products, deal_installments, projects and tasks read Pipedrive API v2; every other stream reads API v1.

Troubleshooting​

  • Missing streams or empty streams: Records are limited to what the token's user can see in Pipedrive. Use a token from a user with broader visibility, or from an admin. mail and mailThreads are empty unless that user has a mailbox connected in Pipedrive. projects, tasks, deal_installments, legacy_teams and permission_set_assignments finish with no records, and an info-level log line naming the stream, when your plan or the token's user can't access that feature.
  • Records missing from incremental streams: Incremental streams only replicate records modified on or after the Start Date, or after the last saved cursor on later syncs. Records that haven't been modified since the Start Date are excluded; move the Start Date earlier or clear the stream to backfill them.
  • Custom fields appear as hash keys: This is expected. See Custom fields.
  • Syncs fail with HTTP 429: The retries were exhausted, which usually means the daily token budget is spent. Reduce the number of enabled streams, increase the interval between syncs, or upgrade the plan.
  • Setup or syncs fail with HTTP 401, 402 or 403: The message carries Pipedrive's own error text. 401 means the token was not copied in full, has been regenerated, or API access is disabled for the user (see Step 1). 402 means the company account is not active. 403 means the token owner lacks permission for that data, or Cloudflare blocked the token after repeated rate-limit violations.

IP allow list​

If you use Airbyte Cloud and your organization restricts access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Reference​

Config fields reference

Field
Type
Property name
string
api_token
integer
num_workers
string
replication_start_date

Changelog​

VersionDatePull RequestSubject
3.0.22026-09-1586184Update dependencies
3.0.12026-09-1485919Test-only release: cover the streams the sandbox cannot populate with mock-server tests and make the 429 retry test deterministic
3.0.02026-09-1485812Read deals, persons, organizations, activities, products, pipelines, stages and deal_products from Pipedrive API v2, add the deals_archived stream, read notes, files, filters, users and leads from their list endpoints instead of Recents, add primary keys to twelve streams, type the date fields and expose deleted deals
2.6.02026-09-1085775Add the call_logs, lead_sources, legacy_teams, projects, tasks, deal_installments, deal_flow and permission_set_assignments streams
2.5.02026-09-1085772Throttle requests to Pipedrive's burst limit with one shared API budget and add the num_workers option for parallel streams
2.4.72026-09-1085774Make Start Date optional with a default, rewrite the spec tooltips and migrate pre-2.0.0 configurations automatically
2.4.62026-09-0985770Classify Pipedrive HTTP errors, wait on x-ratelimit-reset for 429s and skip inaccessible parent records in deal_products and mail
2.4.52026-09-0985767Restructure the documentation and add contributor guides
2.4.42026-09-0985763Set the heartbeat timeout, add a CODEOWNERS entry and tidy the changelog
2.4.32026-09-0985764Use the currencies stream for the connection check and add suggested streams
2.4.22026-09-0985766Make pagination null-safe for responses without additional_data, fixing the mail stream
2.4.12026-09-0985762Fix components.py import failure on Python 3.11+ (use default_factory for decoder) and move to SDM 7.28.3
2.4.02025-02-2854716Refactor: Optimize Parameters, remove redundant code and Improve Manifest Readability
2.3.82025-02-2247292Migrate to manifest only format
2.3.72025-02-0853488Update dependencies
2.3.62025-02-0152986Update dependencies
2.3.52025-01-2552477Update dependencies
2.3.42025-01-1851922Update dependencies
2.3.32025-01-1151305Update dependencies
2.3.22025-01-0450929Update dependencies
2.3.12024-12-2850288Update dependencies
2.3.02024-12-1748615Update airbyte-cdk to use concurrency
2.2.282024-12-1449692Update dependencies
2.2.272024-12-1249041Make the Docker image rootless (requires Airbyte platform 0.64 or later)
2.2.262024-11-0448293Update dependencies
2.2.252024-10-2947743Update dependencies
2.2.242024-10-2847103Update dependencies
2.2.232024-10-1246822Update dependencies
2.2.222024-10-0546487Update dependencies
2.2.212024-09-2846132Update dependencies
2.2.202024-09-2145748Update dependencies
2.2.192024-09-1445556Update dependencies
2.2.182024-09-0745303Update dependencies
2.2.172024-08-3144981Update dependencies
2.2.162024-08-2444644Update dependencies
2.2.152024-08-1744316Update dependencies
2.2.142024-08-1243888Update dependencies
2.2.132024-08-1043679Update dependencies
2.2.122024-08-0343056Update dependencies
2.2.112024-07-2742287Update dependencies
2.2.102024-07-1341729Update dependencies
2.2.92024-07-1041465Update dependencies
2.2.82024-07-0941082Update dependencies
2.2.72024-07-0640778Update dependencies
2.2.62024-06-2540501Update dependencies
2.2.52024-06-2240171Update dependencies
2.2.42024-06-0439095[autopull] Upgrade base image to v1.2.1
2.2.32024-05-2038405[autopull] base image + poetry + up_to_date
2.2.22024-01-1134153prepare for airbyte-lib
2.2.12023-11-0631147Bugfix: handle records with a null data field
2.2.02023-10-2531707Add new stream mail
2.1.02023-10-1031184Add new stream goals
2.0.12023-10-1331151Add additionalProperties in schemas to read custom fields
2.0.02023-08-0929293Migrated to Low-Code CDK
1.0.02023-06-2927832Remove followers_count field from Products stream
0.1.192023-07-0527967Update OrganizationFields and ProductFields with display_field field
0.1.182023-06-0226892Update DialFields schema with pipeline_ids property
0.1.172023-03-2124282Bugfix handle missed cursor_field
0.1.162023-03-0823789Add 11 new streams
0.1.152023-03-0223705Disable OAuth
0.1.142023-03-0123539Fix schema for "activities", "check" works if empty "deals"
0.1.132022-09-1616799Migrate to per-stream state
0.1.122022-05-2313082Remove date-time format from schemas
0.1.112022-05-1612867Add unit tests
0.1.102022-04-2611870Add 3 streams: DealFields, OrganizationFields and PersonFields
0.1.92021-12-078582Update connector fields title/description
0.1.82021-11-167875Extend schema for "persons" stream
0.1.72021-11-157968Update oAuth flow config
0.1.62021-10-056821Add OAuth support
0.1.52021-09-276441Fix normalization error
0.1.42021-08-265943Add organizations stream
0.1.32021-08-265642Remove date-time from deals stream
0.1.22021-07-234912Update money type to support floating point
0.1.12021-07-194686Update spec.json
0.1.02021-07-194686🎉 New source: Pipedrive connector
Was this page helpful?