Advanced Analytica Advanced Analytica: IBOM
← All connectors
Pipedrive logo

Source connector

Pipedrive

Set up Pipedrive as a source and move its data into your chosen destination.

Version 5.0.3 certified generally available

Pipedrive

Use this page to set up the Pipedrive source connector and find reference information.

Prerequisites

  • A Pipedrive account.
  • For OAuth authentication on Airbyte Cloud, you don’t need anything else. You’ll authorise Airbyte’s Pipedrive app during setup.
  • For API token authentication, or self-managed Airbyte, you need a personal API token. API access must be enabled for your Pipedrive user.

Setup guide

Step 1: Set up Pipedrive

You can authenticate the connector with OAuth or a personal API token. Each credential belongs to one Pipedrive user. The connector can only read data that this user can see.

OAuth (default on Airbyte Cloud): You don’t need to prepare anything. During setup, you’ll authorise Airbyte’s Pipedrive app in a browser window. Pipedrive then returns your company’s API host, which the connector uses for every request. Pipedrive asks you to accept all the app’s scopes together. The roles, permission_sets and permission_set_assignments streams depend on the app’s admin scope. Pipedrive only honours this scope when a company admin authorises the app. See Pipedrive’s scopes and permission explanations.

API token:

  1. In the Pipedrive web app, click your account name in the top-right corner. Then select Company settings > Personal preferences > API.
  2. Copy the API token shown on the page. See How to find the API token for screenshots.

You can have one active Pipedrive API token per user. If you regenerate it, update the connector configuration. Each company has its own token if you belong to several companies.

If you can’t see the API tab, 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 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. Complete the fields below, then click Set up source.

Authentication: Choose OAuth2.0 and click Authenticate your Pipedrive account. Alternatively, choose API Token and paste the token you copied in Step 1. Airbyte sends the API token in the x-api-token header with every request. The token never appears in URLs. On self-managed Airbyte, choose API Token unless you’ve registered your own Pipedrive OAuth app. See Pipedrive’s OAuth authorization guide.

Start Date (optional): Enter a UTC date and time in the format YYYY-MM-DDTHH:MM:SSZ, such as 2017-01-25T00:00:00Z. You can also use a space instead of T. If you leave this empty, it defaults to 2010-01-01T00:00:00Z. Incremental streams only replicate records updated on or after this date. Full refresh streams ignore it, except deal_products and deal_installments. These streams only read the deals returned by deals and deals_archived. See Incremental sync and Start Date.

Number of concurrent workers (optional): Set how many streams Airbyte syncs in parallel, from 2 to 10. A value of 1 runs with 2 workers. The default is 3. All requests share one client-side request budget, sized to Pipedrive’s lowest-plan burst limit. Higher values therefore rarely make a sync faster.

When you click Set up source, Airbyte tests the connection by calling the Currencies endpoint. Every credential can read this endpoint. The test therefore passes even when an account has no deals.

Supported sync modes

The Pipedrive source connector supports these 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. The following streams read API v2: deals, deals_archived, persons, organizations, activities, products, pipelines, stages, deal_products, deal_installments, product_variations, projects and tasks. Ten streams support incremental sync. deals, deals_archived, persons, organizations, activities, products, notes and leads filter on the server with updated_since. files and deal_flow filter on the client side. The other twenty-seven streams only support full refresh. The stream names below match those 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 Pipedrive the Start Date or last saved cursor as updated_since. This filter is inclusive. Each incremental run re-emits the record whose update_time matches the saved cursor. Destinations deduplicate this record using the primary key. files reads the full list, sorted by id. It keeps records modified on or after the cursor. files, notes and leads also reread the hour before the saved cursor. This prevents missing records edited while a sync reads the list. deal_flow reads the change history for each deal returned by deals and deals_archived. It keeps changes whose log_time is on or after the cursor. It doesn’t reread the previous hour. pipelines, stages, filters and users use full refresh. The v2 pipelines and stages endpoints have no updated_since parameter. 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. These only cover deals returned by deals and deals_archived for the Start Date. product_variations reads every product’s variations during each sync.

deals and deals_archived request status=open,won,lost,deleted. They return deals deleted within the last 30 days with is_deleted: true. projects requests every project status and returns deleted projects with status: deleted. No other stream requests deleted records. The is_deleted field on other API v2 records and users passes through exactly as Pipedrive returns it. deals_archived delivers archived deals with is_archived: true.

Custom fields

You can add Pipedrive custom fields to deals, persons, organizations, products and activities. The API returns each custom field as a 40-character hash key, not a readable name. API v2 streams expose these values under the custom_fields object. leads and leads_archived use API v1 and return them as top-level hash keys. To match a hash key with its label and type, sync the corresponding *_fields stream. These are deal_fields, person_fields, organization_fields, product_fields or activity_fields. Then join on the key column.

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

Mail streams

mailThreads lists threads from the connected Pipedrive user’s mailbox. It queries the inbox, drafts, sent and archive folders separately. A thread in several folders may therefore appear more than once. mail then requests messages from every thread returned by mailThreads, making one request per thread. Both streams only support full refresh. You can only see mail for the connected Pipedrive user, not the whole company. If that user hasn’t connected a mailbox to Pipedrive through Mail sync, both streams return no records.

Performance considerations

Pipedrive applies per-company, token-based rate limits based on your plan and seat count. The connector limits itself to 20 requests per rolling 2 seconds across all streams. This matches Pipedrive’s lowest-plan burst limit. Bursts therefore rarely trigger a 429, regardless of how many workers you configure. When Pipedrive returns HTTP 429, the connector waits for the window in the x-ratelimit-reset header. If the header is missing, it uses exponential backoff. It retries up to ten times before failing the sync. If the header specifies 300 seconds or more, the connector stops with a retryable error instead of waiting. Two limits apply. The first is a rolling 2-second burst window for each API token. It allows 20 to 120 requests, depending on your plan, and recovers after a short wait. The second is a daily token budget shared across the whole company. It equals 30,000 tokens multiplied by the plan multiplier and seat count. Every API token and app in the company shares this budget. Once exhausted, every request fails until midnight in Pipedrive’s server timezone. Waiting doesn’t help in this case. If your account is nearing its limits, run fewer streams per connection or schedule syncs less often.

These streams make requests for each parent record. They can run slowly on large accounts and consume more of the daily token budget:

  • deal_products makes one request for every 100 deals returned by deals and deals_archived (10 tokens each).
  • product_variations makes one request per product during every sync, regardless of 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 for every 100 deals returned by deals and deals_archived (10 tokens each).

Leave these streams disabled unless you need them.

Limitations and troubleshooting

Expand to see details about Pipedrive connector limitations and troubleshooting.

Connector limitations

The connector handles Pipedrive HTTP errors as follows:

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.
  • The connector replicates deletions for deals and deals_archived for 30 days after deletion (is_deleted: true). It also replicates deletions for projects (status: deleted). Records deleted from other streams remain in your destination until you clear and resync the stream.
  • With OAuth, requests use the company host returned by Pipedrive during authorisation (https://<company>.pipedrive.com/api/...). With an API token, they use https://api.pipedrive.com.
  • With OAuth, Pipedrive access tokens expire after 60 minutes. The connector refreshes them automatically. The refresh token expires if unused for 60 days. You must re-authenticate a source that hasn’t synced for 60 days. See Pipedrive’s OAuth authorization guide.
  • With OAuth, a 403 “Scope and URL mismatch” means Airbyte’s Pipedrive app lacks a required stream scope. This causes every stream to fail with a configuration error, including streams that otherwise skip a 403.

Troubleshooting

  • Missing streams or empty streams: You can only access records visible to the connected Pipedrive user. Connect as a user with broader visibility or an admin. mail and mailThreads remain empty unless that user has connected a mailbox in Pipedrive. Some streams finish without records when your plan or connected user can’t access the feature. These are projects, tasks, deal_installments, legacy_teams and permission_set_assignments. An information-level log entry identifies the stream.
  • Records missing from incremental streams: Incremental streams only replicate records modified on or after the Start Date. Later syncs use the last saved cursor instead. Records unchanged since the Start Date are excluded. To backfill them, move the Start Date earlier or clear the stream.
  • Custom fields appear as hash keys: This is expected. See Custom fields.
  • Syncs fail with HTTP 429: The connector exhausted its retries, usually because the daily token budget is spent. Every integration in your Pipedrive company shares this budget, so another integration can also spend it. Enable fewer streams, increase the interval between syncs or upgrade the plan.
  • Setup or syncs fail with HTTP 401, 402, 403 or 415: The message includes Pipedrive’s error text. A 415 means your company hasn’t enabled a feature that the stream reads. Enable it in Pipedrive or deselect the stream. With an API token, a 401 can mean the token is incomplete, regenerated or disabled for the user. See Step 1. With OAuth, the connector first refreshes the access token once and retries. If a 401 remains, the authorisation has expired or been revoked. Re-authenticate the source. A 402 means the company account isn’t active. A 403 can mean the connected user lacks permission for the data. It can also mean Cloudflare blocked requests after repeated rate-limit violations. With OAuth, “Scope and URL mismatch” means Airbyte’s app lacks a scope. Deselect the stream and contact Airbyte support. For 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: After repeated rate-limit violations, Cloudflare blocks requests with an HTML page. Reduce the sync frequency and retry later. If the issue continues, Pipedrive may no longer serve an endpoint that 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 restrict access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Changelog

VersionDatePull RequestSubject
5.0.32026-11-1091677Update dependencies
5.0.22026-11-0390685Update dependencies
5.0.12026-11-0290176Mark the connector as certified
5.0.02026-11-0190177Type the remaining date and time fields on nine streams and correct declared shapes on goals, leads, mailThreads and deal_fields; declare fields Pipedrive returns without documenting them
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
Advanced Analytica

Most businesses are sitting on information they can’t use at speed. The people who hold it are busy, and when they leave, the knowledge goes with them. The documents are static, and the processes around them weren’t designed for AI.

Advanced Analytica works with these businesses to turn that information into structured data assets. Once they're integrated, AI systems can govern it, and the business can use it. We bring in the strategy, the specification and the AI skills to rework how the business operates.

MOVE FAST. STAY SAFE.