Pipedrive API v2 Migration: What Changed and How to Update Your Integrations

Quick Summary

Pipedrive’s move to API v2 introduces breaking changes that affect every integration built on the v1 REST API. If your team connects Pipedrive CRM to external tools via custom code, Zapier, Make, or direct API calls, you need to understand what changed and act before deprecated endpoints stop responding. This article covers the three most critical areas of the migration: the new token-based rate limiting (TBRL) system that replaces per-second request limits, the v1 endpoints deprecated since March 2025, and the updated OAuth 2.0 authentication flow that all multi-user integrations must now adopt.

What you will learn in this article: How Pipedrive CRM’s token-based rate limits (TBRL) work and how to code against them, which v1 endpoints are deprecated and their v2 replacements, how the OAuth 2.0 changes since March 2025 affect your authentication flow, and a step-by-step migration checklist for updating live integrations safely.

---

Why Did Pipedrive CRM Introduce API v2 and What Does It Change?

Pipedrive CRM’s v1 API served developers well for over a decade, but its architecture reflected the constraints of an earlier era. The v1 API used blunt per-second and per-day request caps, returned inconsistent response structures across endpoints, and relied on API key authentication that no longer meets modern security standards for multi-user CRM integrations.

API v2 addresses all three shortcomings simultaneously. It introduces a token-based rate limiting system that rewards well-behaved integrations with higher effective throughput, standardises response envelopes across all endpoints so developers can write predictable error-handling code, and replaces static API keys with a fully compliant OAuth 2.0 flow that scopes permissions at the user and integration level.

Furthermore, the v2 migration is not purely additive. Pipedrive deprecated a significant set of v1 endpoints in March 2025 and assigned sunset dates after which those endpoints return error responses rather than data. Consequently, migrating from v1 to v2 is no longer optional for any team that depends on Pipedrive CRM integrations for live sales operations.

Area of Change	API v1 Behaviour	API v2 Behaviour
Rate limiting model	Fixed requests per second / per day	Token bucket (TBRL) — burst-aware replenishment
Authentication	Static API key or basic OAuth	OAuth 2.0 with granular scopes — mandatory for multi-user
Response structure	Inconsistent per endpoint	Standardised: data, additional_data, error envelope
Pagination	Offset-based (start + limit)	Cursor-based (next_cursor in additional_data)
Deprecated endpoints	All v1 endpoints active	25+ v1 endpoints deprecated; v2 replacements available
Phone / email fields	String values	Array of objects with value, label, primary properties
Activity date-time	Separate due_date + due_time strings	Single due_at ISO 8601 timestamp
Error codes	Varied HTTP status codes	Consistent codes with machine-readable error keys

---

How Does the New Token-Based Rate Limiting System Work in Pipedrive CRM API v2?

Token-based rate limiting (TBRL) replaces the simple per-second cap that constrained v1 integrations. Understanding how TBRL works is essential before you migrate, because patterns that behaved correctly under v1 rate limits can generate sustained 429 errors under TBRL if the integration does not implement backoff and token-aware request management.

What Is the Token Bucket Model and How Does It Apply to Pipedrive CRM?

TBRL uses a token bucket algorithm. Pipedrive CRM assigns each integration a bucket with a defined maximum capacity. Every API request consumes one token. The bucket replenishes at a fixed rate per second up to its maximum. When the bucket empties, Pipedrive CRM returns 429 Too Many Requests and includes a Retry-After header specifying how many seconds to wait before the next call.

The critical difference from v1 is that TBRL rewards intelligent bursting. An integration that pauses for ten seconds accumulates tokens — it can then send a burst of requests before the bucket depletes again. This suits the way most Pipedrive CRM automation workflows actually operate: quiet during business hours, then processing a batch of records after a trigger event or at the end of the day.

What Are the TBRL Limits for Each Pipedrive CRM Plan?

Pipedrive CRM Plan	Bucket Capacity	Replenishment Rate	Effective Sustained Rate
Essential	100 tokens	10 tokens / second	~10 req/s sustained; 100 req burst
Advanced	200 tokens	20 tokens / second	~20 req/s sustained; 200 req burst
Professional	400 tokens	40 tokens / second	~40 req/s sustained; 400 req burst
Power	600 tokens	60 tokens / second	~60 req/s sustained; 600 req burst
Enterprise	1,000 tokens	100 tokens / second	~100 req/s sustained; 1,000 req burst

Always verify current TBRL limits at developers.pipedrive.com before designing high-volume integrations — Pipedrive CRM updates plan-level limits periodically and the developer documentation reflects the most current values.

How Should You Handle 429 Responses from Pipedrive CRM API v2?

Every integration calling Pipedrive CRM API v2 must implement a retry loop with Retry-After-aware backoff for 429 responses. Read the Retry-After header value from the 429 response and wait exactly that many seconds before retrying. Do not use a fixed delay — it either wastes time or repeats the 429 cycle.

// Pseudocode: handle 429 with Retry-After header

response = await callPipedriveAPI(endpoint)

if response.status === 429:

    retryAfter = parseInt(response.headers[‘Retry-After’]) || 5

    await sleep(retryAfter * 1000)

    response = await callPipedriveAPI(endpoint)  // single retry

Additionally, implement a request queue for any integration that fires multiple Pipedrive CRM API calls in quick succession — for example, a webhook handler that creates a deal, two activities, and a note simultaneously. A queue with a configurable rate cap keeps your token bucket healthy across burst events and prevents cascading 429 errors from disrupting live pipeline data.

---

Which Pipedrive CRM v1 Endpoints Were Deprecated in March 2025?

Pipedrive deprecated the first wave of v1 endpoints in March 2025. Integrations calling these endpoints currently receive a Deprecation: true response header as an early warning signal. After the assigned sunset date, those endpoints return 410 Gone errors — the data simply stops flowing.

What Are the Most Commonly Used Deprecated v1 Endpoints and Their v2 Replacements?

Deprecated v1 Endpoint	Method	v2 Replacement	Key Breaking Change
GET /v1/deals	GET	GET /v2/deals	Cursor pagination; enriched response schema
POST /v1/deals	POST	POST /v2/deals	Currency now object; new required field structure
PUT /v1/deals/{id}	PUT	PATCH /v2/deals/{id}	v2 uses PATCH not PUT; partial updates only
GET /v1/persons	GET	GET /v2/persons	Phone and email now arrays of objects, not strings
POST /v1/persons	POST	POST /v2/persons	Phone/email payload format changed
GET /v1/organizations	GET	GET /v2/organizations	Address object restructured; cursor pagination
GET /v1/activities	GET	GET /v2/activities	Type field now uses ID not key string
POST /v1/activities	POST	POST /v2/activities	due_date + due_time merged to due_at (ISO 8601)
GET /v1/dealFields	GET	GET /v2/deals/fields	URL path changed; field schema updated
GET /v1/pipelines	GET	GET /v2/pipelines	Response envelope restructured

What Response Structure Changes Break Existing v1 Integration Code?

Three structural changes break the most existing Pipedrive CRM integrations and deserve special attention during migration:

• Phone and email arrays: v1 returned these as plain strings. v2 returns arrays of objects — each containing value, label, and primary keys. Code that reads person.email directly as a string returns undefined on v2 without throwing an error, causing silent data loss in contact sync integrations.
• Activity date-time merger: v1 split due date and time into separate due_date and due_time fields. v2 combines them into a single due_at ISO 8601 timestamp. Integrations that construct activity payloads must merge these fields and convert to ISO 8601 format before calling v2 endpoints.
• Cursor pagination: v1 used start and limit offset parameters. v2 returns a next_cursor in the additional_data object. Every integration that pages through lists of deals, contacts, or activities must replace its offset loop with a cursor-following loop that continues until next_cursor returns null.

Silent Data Loss Risk — Phone and Email Arrays: Reading person.phone or person.email as a string after switching to v2 endpoints returns undefined rather than throwing an error. Your integration continues running without exceptions but saves blank contact details to every downstream system. Update all contact field parsing to handle the v2 array format — extract the primary: true object or fall back to the first array element — before switching to v2 endpoints.

---

How Did OAuth 2.0 Change for Pipedrive CRM Integrations Since March 2025?

OAuth 2.0 support existed in Pipedrive CRM before v2, but the March 2025 update made it mandatory for all integrations that access data on behalf of multiple users and began deprecating static API key authentication for those use cases. Understanding exactly what changed determines whether your existing authentication method still works — or needs an immediate update.

What Authentication Methods Does Pipedrive CRM API v2 Support?

Auth Method	v2 Support	Best Use Case	Action Required
Personal API Token	Yes — own data only	Single-user scripts, testing, internal tools	No change needed
OAuth 2.0 (Authorization Code)	Yes — required for multi-user apps	Marketplace apps, SaaS integrations, agency tools	Migrate from API key if not already on OAuth
OAuth 2.0 (Client Credentials)	Yes — server-to-server	Backend services, automated batch jobs	New in v2; replaces shared API key patterns
Static API Key (shared / team)	Deprecated for multi-user	Was used for team-wide integrations	Replace with OAuth 2.0 immediately

What Changed in the OAuth 2.0 Flow Itself for Pipedrive CRM?

The authorization and token exchange endpoint URLs changed in March 2025. Integrations using the old v1 OAuth endpoint — https://oauth.pipedrive.com/oauth/authorize — must update to the v2 endpoint: https://oauth.pipedrive.com/v2/oauth/authorize. The token exchange endpoint similarly changed to https://oauth.pipedrive.com/v2/oauth/token.

Additionally, v2 OAuth introduces granular permission scopes that replace the broad access model of v1. Rather than granting your integration access to all Pipedrive CRM data, you now request specific scopes — for example, deals:read, deals:write, persons:read — and Pipedrive CRM restricts the integration to exactly those resources. This aligns Pipedrive CRM with enterprise security standards and reduces the blast radius of any compromised integration credential.

How Do You Update Token Refresh Logic for Pipedrive CRM v2 OAuth?

Access token lifetime shortened in v2 — tokens now expire after one hour. Integrations that make infrequent API calls must refresh tokens proactively rather than waiting for a 401 Unauthorized response to trigger a refresh, which causes request failures during active sync windows.

The safest implementation stores the token expiry timestamp alongside the access token, checks it before every API call, and refreshes proactively when fewer than five minutes remain. This single change prevents the most common Pipedrive CRM OAuth failure pattern — a nightly sync job that starts processing correctly, then hits a token expiry mid-run and drops the remaining records.

OAuth 2.0 Scope Reference for Pipedrive CRM v2: Core scopes: deals:read, deals:write, persons:read, persons:write, organizations:read, organizations:write, activities:read, activities:write, pipelines:read, users:read. Request only the scopes your integration actually needs. Pipedrive CRM displays the full scope list to users on the authorization screen — overly broad requests reduce installation conversion rates for marketplace apps.

---

How Do You Migrate a Live Pipedrive CRM Integration from v1 to v2?

Migrating a production integration requires a phased approach that keeps Pipedrive CRM data flowing without interruption. A big-bang cutover — replacing all v1 calls simultaneously — risks service disruption if any endpoint mapping or response parsing contains an error. Instead, migrate one object type at a time, validate each change in staging, and deploy incrementally to production.

What Is the Recommended Step-by-Step Migration Process?

1. Audit all v1 endpoint calls: Search your codebase for every call to /v1/ paths. List each with its HTTP method, request payload, and response fields your code consumes.
2. Add Deprecation header logging: Log the Deprecation response header on all live API calls. Any endpoint returning Deprecation: true needs priority migration before its sunset date.
3. Set up a v2 staging environment: Use a separate Pipedrive CRM account to test v2 endpoint calls without touching live pipeline data.
4. Migrate OAuth credentials first: Update to the v2 OAuth endpoints and granular scopes before changing any endpoint URLs. Confirm token acquisition, expiry tracking, and refresh work end-to-end.
5. Migrate GET endpoints before write endpoints: Start with read-only calls — validate phone/email array parsing and cursor pagination logic before enabling write operations.
6. Update pagination loops: Replace all offset-based pagination with cursor-following loops that read next_cursor from additional_data until it returns null.
7. Migrate write endpoints: Update POST and PATCH payloads — activity due_at format, phone/email array structure, currency objects on deals.
8. Implement TBRL-aware retry logic: Add the Retry-After backoff pattern and a request queue before deploying to production.
9. Monitor 4xx error rates for 24 hours: A spike in 422 errors indicates payload format mismatch; a spike in 401 errors indicates an OAuth configuration problem.

Migration Timeline Recommendation: Allow at least two weeks for a full v1-to-v2 migration on a production Pipedrive CRM integration. Week 1: audit, staging setup, OAuth migration, and GET endpoint updates. Week 2: write endpoint updates, pagination migration, TBRL load testing, and production deployment with 24-hour monitoring. Do not rush PATCH /v2/deals write endpoints — malformed payloads can corrupt live deal data.

How Do You Test Pipedrive CRM API v2 Integrations Before Going Live?

Beyond functional testing of individual endpoints, run three additional validation passes before the production cutover:

• Rate limit burst test: Fire 150% of your peak typical request volume in a burst to confirm your backoff logic handles 429 responses without dropping records or entering infinite retry loops.
• Token expiry test: Force an access token expiry by setting the stored expiry timestamp to the past, then confirm your integration proactively refreshes and continues processing without manual intervention.
• Pagination completeness test: Compare total record counts returned by v1 offset pagination vs v2 cursor pagination on the same Pipedrive CRM dataset to confirm no records are skipped or doubled in the cursor loop.

---

Conclusion: How Do You Stay Ahead of Pipedrive CRM API Changes Going Forward?

Pipedrive CRM‘s move to API v2 is the most significant platform change for developers and integration builders in the CRM’s history. The three pillars of the migration — token-based rate limits, deprecated v1 endpoints, and updated OAuth 2.0 — each require distinct code changes, and attempting to handle all three simultaneously increases delivery risk unnecessarily.

Instead, approach the migration in the sequence that minimises disruption: OAuth first, then read endpoints, then write endpoints, then pagination. At each step, validate changes against a staging Pipedrive CRM environment before pushing to production, and monitor 4xx error rates for 24 hours after each deployment. Add the Deprecation header to your API logging immediately — it surfaces exactly which v1 endpoints your Pipedrive CRM integration still calls before they silently break after their sunset dates.

Going forward, subscribe to the Pipedrive Developer Changelog at developers.pipedrive.com to receive early notice of future deprecations. Pipedrive CRM commits to a minimum 12-month deprecation notice period for v2 endpoints, giving your team a predictable planning window. Teams that build on v2 from this point — with TBRL-aware retry logic, scoped OAuth 2.0, and cursor-based pagination — will handle future Pipedrive CRM API evolution with minimal disruption to live sales operations.

---

Frequently Asked Questions

---