Skip to main content

Pipedrive

Availability
Available CoreAvailable StandardAvailable PlusAvailable ProAvailable Enterprise FlexAvailable PyAirbyte
Connector type (beta)
Available Data replicationNot available Agent(learn more)
Support Level
Marketplace
Connector Version
4.0.1 (last updated 3 days ago)
Sync Success Rate
Low
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 in the x-api-token header 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. A space instead of T also works. Defaults to 2010-01-01T00:00:00Z when left empty. Incremental streams only replicate records updated on or after this date. Full refresh streams ignore it, except deal_products and deal_installments, which only read the deals that deals and deals_archived return. See Incremental sync and Start Date.

Number of concurrent workers (optional): How many streams Airbyte syncs in parallel, from 2 to 10; a value of 1 runs with 2 workers. 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, product_variations, 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-seven 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 the deals returned by deals and deals_archived, fetched for 100 deals per request from API v2 GET /api/v2/deals/products.
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 id; the connector reads the full list and keeps records modified on or after the cursor minus one hour. Cursor: update_time.
filtersFull RefreshAPI v1 /filters.
goalsFull RefreshEveryone's goals, read once per assignee type (person, team and company) from Goals.
lead_labelsFull RefreshLeadLabels
lead_sourcesFull RefreshLeadSources
leadsFull Refresh, IncrementalLeads that are not archived (Leads) with the inclusive updated_since filter, sorted by id; each sync re-reads the hour before the cursor. Cursor: update_time.
leads_archivedFull RefreshArchived leads (Leads getArchivedLeads), which leads leaves out. Same fields as leads.
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, sorted by id; each sync re-reads the hour before the cursor. 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
product_variationsFull RefreshVariations of every product (Products getProductVariations), one request per product. The Start Date does not apply.
productsFull Refresh, IncrementalAPI v2 api/v2/products, cursor: update_time.
projectsFull RefreshActive and archived projects (Projects), including deleted projects with status: deleted. 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 id and keeps the records modified on or after the cursor. files, notes and leads also re-read the hour before the saved cursor, so a record edited while a sync was reading the list is not missed. deal_flow reads the change history of each deal that deals and deals_archived return and keeps the changes whose log_time is on or after the cursor; it doesn't re-read the previous hour. 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. Full refresh streams ignore the Start Date and return all records, except deal_products and deal_installments, which only cover the deals that deals and deals_archived return for the Start Date. product_variations reads the variations of every product on every sync.

deals and deals_archived request status=open,won,lost,deleted, so deals deleted within the last 30 days are returned with is_deleted: true. projects requests every project status, so deleted projects are returned with status: deleted. 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; leads and leads_archived come from API v1 and return them as top-level hash keys. 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: a rolling 2-second burst window per API token (20 to 120 requests depending on your plan) that recovers after a short wait, and a daily token budget for the whole company (30,000 tokens times the plan multiplier and the number of seats, shared by every API token and app in the company) that, once exhausted, rejects every request until midnight in Pipedrive's server timezone. Waiting does not help in the second case. If your account is close to its limits, run fewer streams per connection or schedule syncs less often.

The following streams make requests per parent record, so they can be slow on large accounts and spend more of the daily token budget:

  • deal_products makes one request per 100 deals returned by deals and deals_archived (10 tokens each).
  • product_variations makes one request per product on every sync, whatever the Start Date (10 tokens each).
  • mail makes one request per mail thread (20 tokens each).
  • deal_flow makes one request per deal returned by deals and deals_archived (40 tokens each).
  • deal_installments makes one request per 100 deals returned by deals and deals_archived (10 tokens each).

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_flow, mail and product_variations, a 403 on a single parent record is skipped and the sync continues; deal_products asks for 100 deals at once, so a 403 skips that batch. If the token can't read any deal products, deal changes, mail messages or product variations at all, those 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. Cloudflare's HTML 403, sent after repeated rate-limit violations, always fails the sync.
404, 410For deal_flow, mail and product_variations, a parent deal, mail thread or product deleted after the parent stream was read is skipped; deal_products asks for 100 deals at once and Pipedrive leaves out deals it no longer has. legacy_teams returns no records on 404 or 410, projects and tasks on 404, and permission_set_assignments skips a permission set without assignments (404). On other streams these fail the sync.
415Pipedrive reports that a feature isn't enabled for your company. legacy_teams, projects, tasks and deal_installments return no records; other streams fail with a configuration error that asks you to enable the feature or deselect the stream.
429Rate limited; retried as described under Performance considerations.
500, 502, 503, 504Temporary Pipedrive errors; retried with backoff.
501The sync fails with a system error: the connector sent a request Pipedrive does not implement. Report it to Airbyte.
  • Deletions are replicated for deals and deals_archived, for 30 days after the deletion (is_deleted: true), and for projects (status: deleted). Records deleted in other streams stay in your destination until you clear and resync the stream.
  • The connector authenticates with a personal API token only. It doesn't support OAuth.

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. The budget is shared by every integration in your Pipedrive company, so another integration can spend it too. Reduce the number of enabled streams, increase the interval between syncs, or upgrade the plan.
  • Setup or syncs fail with HTTP 401, 402, 403 or 415: The message carries Pipedrive's own error text. 415 means a feature the stream reads isn't enabled for your company: enable it in Pipedrive or deselect the stream. 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
4.1.02026-10-1488479Add the product_variations and leads_archived streams, read everyone's goals and deleted projects, declare missing Pipedrive fields, send the API token in a header and fix error handling and paging gaps
4.0.12026-10-1388753Update dependencies
4.0.02026-10-0687669Correct declared field types to match the Pipedrive API reference (lead ids on notes and files are strings) and declare the missing vendor fields on mail, mailThreads, notes and permission_sets
3.0.52026-10-0687979Update dependencies
3.0.42026-09-2987265Update dependencies
3.0.32026-09-2286762Update dependencies
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?