Skip to main content

Pipedrive

Availability
Available CoreAvailable StandardAvailable PlusAvailable ProAvailable Enterprise FlexAvailable PyAirbyte
Connector type
Available Data replicationNot available Agent(learn more)
Support Level
Marketplace
Connector Version
4.1.3 (last updated 2 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.
  • To authenticate with OAuth on Airbyte Cloud, nothing else. You authorize Airbyte's Pipedrive app during setup.
  • To authenticate with an API token, or on self-managed Airbyte, a personal API token. API access must be enabled for your Pipedrive user.

Setup guide​

Step 1: Set up Pipedrive​

The connector authenticates with OAuth or with a personal API token. Either credential belongs to one Pipedrive user, so the connector can only read data that user is allowed to see.

OAuth (default on Airbyte Cloud): No preparation is needed. During setup you authorize Airbyte's Pipedrive app in a browser window, and Pipedrive returns your company's own API host, which the connector uses for every request. Pipedrive asks you to accept all of the app's scopes at once. The roles, permission_sets and permission_set_assignments streams rely on the app's admin scope, which Pipedrive only honors when the user who authorizes the app is a company admin. See Pipedrive's scopes and permission explanations.

API token:

  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.

Authentication: Choose OAuth2.0 and click Authenticate your Pipedrive account, or choose API Token and paste the token you copied in Step 1. Airbyte sends the API token in the x-api-token header on every request; it never appears in URLs. On self-managed Airbyte, choose API Token unless you registered your own Pipedrive OAuth app (see Pipedrive's OAuth authorization guide).

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 credential 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 connected 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, and fails if Pipedrive retires the endpoint.
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 user; 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 Pipedrive user the source connects as. 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 connected Pipedrive user, 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 (an HTML 404 page fails instead); deal_products asks for 100 deals at once and Pipedrive leaves out deals it no longer has. projects and tasks return no records on a JSON 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.
  • With OAuth, requests go to the company host Pipedrive returned during authorization (https://<company>.pipedrive.com/api/...); with an API token they go to https://api.pipedrive.com.
  • With OAuth, Pipedrive issues access tokens that expire after 60 minutes, and the connector refreshes them automatically. The refresh token itself expires if it isn't used for 60 days, so a source that doesn't sync for 60 days must be re-authenticated. See Pipedrive's OAuth authorization guide.
  • With OAuth, a 403 "Scope and URL mismatch" means Airbyte's Pipedrive app lacks the scope a stream needs. It fails the sync with a configuration error on every stream, including those that otherwise skip a 403.

Troubleshooting​

  • Missing streams or empty streams: Records are limited to what the connected Pipedrive user can see. Connect as a user with broader visibility, or as 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 connected 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. With an API token, 401 means the token was not copied in full, has been regenerated, or API access is disabled for the user (see Step 1); with OAuth the connector first refreshes the access token once and retries, so a 401 that remains means the authorization expired or was revoked: re-authenticate the source. 402 means the company account is not active. 403 means the connected user lacks permission for that data, Cloudflare blocked the requests after repeated rate-limit violations, or, with OAuth and the text "Scope and URL mismatch", Airbyte's app lacks a scope: deselect the stream and contact Airbyte support (with your own OAuth app, grant the scope in the Pipedrive Developer Hub and re-authenticate).
  • Syncs fail because Pipedrive answered with an HTML page instead of JSON: Cloudflare blocks the requests with an HTML page after repeated rate-limit violations: reduce the sync frequency and retry later. If it keeps happening, Pipedrive may no longer serve an endpoint the stream reads; report it to Airbyte with the stream name. This message comes from deal_flow, mail, product_variations, deal_products, deal_installments, projects, tasks, legacy_teams and permission_set_assignments.

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.2.12026-10-2890148Read call_logs, product_variations and leads_archived in the standard tests, fail legacy_teams when Pipedrive retires its endpoint instead of returning no records, and allow null on eight mailThreads fields the API reference marks nullable
4.2.02026-10-2885773Add OAuth2.0 as the default authentication; existing API token configs move into credentials automatically
4.1.32026-10-2790008Update dependencies
4.1.22026-10-2489714Rebuild error handling for child and plan-gated streams as one handler per stream; an unexpected HTML page on those streams, such as an endpoint Pipedrive no longer serves, now fails the sync instead of reading as empty or being retried
4.1.12026-10-2089349Update dependencies
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?