---
title: "WordPress Pipedrive Integration: API, Token and Limits"
description: "A WordPress Pipedrive integration on the REST API: the x-api-token header, search-then-create for persons and leads, and the token budget behind every call."
url: "https://wpwebhooks.org/blog/wordpress-pipedrive-integration/"
date: "2026-09-10"
---

# WordPress Pipedrive Integration: API, Token and Limits

**TL;DR:** A WordPress Pipedrive integration is two API calls and one budget you have to understand before you ship.

-   Authenticate with the account's **API token** in an `x-api-token` header. It is tied to one user, and only one is active at a time.
-   Search the person by email first, create it only if the search is empty, then create the **lead** that references it. That order is what keeps the CRM free of duplicates.
-   Pipedrive meters calls in **tokens**: a daily budget of 30,000 × plan multiplier × seats, plus a burst limit per two-second window. A search costs 40 tokens; an update costs 10.
-   Never make these calls inside the request the visitor is waiting on. Queue them.

/ Official

## Is there an official Pipedrive WordPress plugin?

One, and it does something narrower than the phrase suggests. Pipedrive publishes the [LeadBooster Chatbot](https://wordpress.org/plugins/leadbooster-by-pipedrive/) on WordPress.org: it embeds Pipedrive's chatbot on your pages, qualifies visitors in conversation and drops them into your pipeline as deals. It requires the paid LeadBooster add-on on your Pipedrive account, and it captures only what the chatbot asks for. It does not watch your forms, your orders or your user registrations.

Everything else on the market is third-party. Form builders such as [WPForms](https://wpforms.com/features/pipedrive-addon/) sell a Pipedrive add-on for their own forms; connector plugins map a handful of form plugins to the persons and deals endpoints. Each covers one source. If the event you care about is a WooCommerce order, a membership renewal or a custom post type, or if your form plugin is not on the add-on's list, you are back to the REST API, which is what this article covers.

/ Auth

## How does a WordPress site authenticate to the Pipedrive API?

With a per-user API token, sent in the `x-api-token` request header.¹ Every user in a Pipedrive account has one, found under the personal preferences, and Pipedrive's [authentication guide](https://pipedrive.readme.io/docs/core-api-concepts-authentication) states the two constraints that matter for a server integration: the token is tied to a specific user and company, and only one active token can exist for that user at a time. Regenerate it and every integration using the old one stops.

The base URL carries the company subdomain: `https://{company}.pipedrive.com/api/v2/`. OAuth 2.0 exists as well, but it is the path for apps listed on the Pipedrive Marketplace, where the token belongs to whoever installs the app. For your own site talking to your own account, the API token is the documented choice and the simpler one.

Two consequences follow from "tied to one user". First, the records you create are owned by that user unless you pass `owner_id`, so a token from the sales director makes the sales director the owner of every web lead. Create a dedicated integration user. Second, if that user is deactivated when they leave the company, the token dies with them, and the integration fails with a `401` on a Tuesday months later. Treat a `401` as "stop and alert", not "retry".

FIG 01 — Search first, then create: the two-call shape that keeps Pipedrive free of duplicates

/ Objects

## Should a WordPress event create a person, a lead, or a deal?

A person and a lead, in that order. Pipedrive's model separates the human from the opportunity: a **person** is the contact record, a **lead** is an unqualified opportunity that sits in the Leads Inbox, and a **deal** is a qualified opportunity in a pipeline stage. A website form or a first order is, by definition, unqualified, so it belongs in the inbox where a salesperson triages it, not in a pipeline stage where it skews the forecast.

The lead endpoint enforces this. [POST /api/v1/leads](https://developers.pipedrive.com/docs/api/v1/Leads) requires a `title` and either a `person_id` or an `organization_id`, so you cannot create a lead without a person to attach it to. That is why the person call comes first, and why the search that precedes the person call is the piece most tutorials leave out.

The [persons API](https://developers.pipedrive.com/docs/api/v1/Persons) moved to v2, and the v2 shape differs from the old one in a way that breaks copied snippets: `emails` and `phones` are arrays of objects, each with `value`, `primary` and `label`. Sending a plain string for `email` is accepted by nothing.

PHP — find or create the person, then the lead

```
function pd_request( $method, $path, $body = null ) {
    $res = wp_remote_request( 'https://' . PD_COMPANY . '.pipedrive.com' . $path, [
        'method'  => $method,
        'timeout' => 10,
        'headers' => [
            'x-api-token'  => PD_TOKEN,
            'Content-Type' => 'application/json',
        ],
        'body'    => $body ? wp_json_encode( $body ) : null,
    ] );
    if ( is_wp_error( $res ) ) {
        return $res;
    }
    return [
        'code' => wp_remote_retrieve_response_code( $res ),
        'body' => json_decode( wp_remote_retrieve_body( $res ), true ),
    ];
}

// 1. Search by email. exact_match=true allows a 1-character term and
//    returns only full matches. Costs 40 tokens.
$q      = http_build_query( [ 'term' => $email, 'fields' => 'email', 'exact_match' => 'true', 'limit' => 1 ] );
$found  = pd_request( 'GET', '/api/v2/persons/search?' . $q );
$person = $found['body']['data']['items'][0]['item']['id'] ?? null;

// 2. Create the person only when the search came back empty.
if ( ! $person ) {
    $created = pd_request( 'POST', '/api/v2/persons', [
        'name'     => $name,
        'owner_id' => PD_INTEGRATION_USER,
        'emails'   => [ [ 'value' => $email, 'primary' => true, 'label' => 'work' ] ],
        'phones'   => $phone ? [ [ 'value' => $phone, 'primary' => true, 'label' => 'work' ] ] : [],
    ] );
    $person = $created['body']['data']['id'] ?? null;
}

// 3. The lead. Leads are still v1; title + person_id are the required pair.
$lead = pd_request( 'POST', '/api/v1/leads', [
    'title'     => $name . ' — website enquiry',
    'person_id' => $person,
    'owner_id'  => PD_INTEGRATION_USER,
] );
```

Three calls when the person is new, two when it already exists. The search is the expensive one at 40 tokens, and it is also the one that makes the whole sequence safe to run twice: a redelivered event finds the person it created the first time and attaches a second lead to it, which a salesperson can merge in seconds. The alternative, a second person record with the same email, is the kind of duplicate that quietly poisons reporting for months.

Leads have no built-in duplicate check on the API, so a repeated delivery does produce two leads. If that matters, store the returned lead id against the WordPress record and skip the lead call when it is already set.

> Search, then person, then lead. Reverse any two of those and you either cannot create the lead at all or you create a person you already had. — the order of operations

/ Limits

## What are the Pipedrive API rate limits, and what does a lead actually cost?

Pipedrive meters two things at once, and both answer with a `429`.² The first is a **daily token budget**, computed per account: 30,000 base tokens × a plan multiplier × the number of seats, plus any purchased top-ups. The multipliers are 1 for Lite, 2 for Growth, 5 for Premium and 7 for Ultimate. The second is a **burst limit** per two-second window, which for API-token requests is 20 on Lite, 40 on Growth, 100 on Premium and 120 on Ultimate. The search endpoint has its own burst cap of 10 requests per two seconds on every plan.

Different operations cost different tokens. Pipedrive publishes costs for some of them:

| Operation | Tokens | Where it shows up here |
| --- | --- | --- |
| Get a single entity | 2 | Reading a person back by id |
| Get a list of entities | 20 | Paging through persons |
| Update a single entity | 10 | Changing a person |
| Delete a single entity | 6 | — |
| Search for entities | 40 | The email lookup, every time |
| Create a single entity | not published | The person and the lead calls |

The create cost is not in Pipedrive's published table, so budget it at the update figure of 10 and check the `x-daily-requests-left` header after your first real day. On that assumption, one new web lead costs 40 + 10 + 10 = **60 tokens**, and a lead for a returning person costs 40 + 10 = **50**.

-   Lite, one seat: 30,000 × 1 × 1 = 30,000 tokens ÷ 60 = **500 new leads a day** before anything else touches the API.
-   Growth, three seats: 30,000 × 2 × 3 = 180,000 ÷ 60 = **3,000 a day**.
-   Premium, ten seats: 30,000 × 5 × 10 = 1,500,000 ÷ 60 = **25,000 a day**.

Five hundred a day sounds like plenty for a contact form until you notice it is shared with every other integration on the account, and that a retry loop with no cap spends the same budget for nothing. The burst limit bites differently: a newsletter that sends 200 people to a landing page in the same minute produces a burst of form submissions, and on Lite the search endpoint allows 10 of them per two seconds. The eleventh gets a `429`, and if your code treats that as a failure rather than a "wait", the lead is gone.

Every response carries `x-ratelimit-limit`, `x-ratelimit-remaining` and `x-ratelimit-reset` for the burst window. Read them. A `429` is the one status where retrying later is exactly right; a `400` from a malformed `emails` array will fail the same way on every attempt and only burns tokens.

![Cyberpunk illustration of two mismatched figures hauling on separate levers in a bank of heavy interlocked hand levers, the nearest one looking down the frame towards the other lever rather than at his own hands while a counter wheel runs down beside him.](https://wpwebhooks.org/blog/wordpress-pipedrive-integration/og_image.jpg)

/ Failure

## Should the Pipedrive calls run inside the WordPress request?

No, and the reason is sharper here than with most APIs because there are two or three sequential calls, not one. A form submission that waits for a search, then a create, then a lead is waiting on three round trips to Pipedrive's servers, and with a 10-second timeout on each, a slow afternoon at Pipedrive becomes a 30-second form for your visitor. PHP-FPM workers pile up behind it, and the burst limit above turns a traffic spike into a queue of visitors staring at a spinner.

Record the intent when the hook fires, return to the visitor immediately, and let a background worker own the three calls. That worker is also where the `429` handling belongs: it can sleep until `x-ratelimit-reset` and try again, which a synchronous request never can. The trade is that the lead appears in the inbox a few seconds later rather than instantly, which no salesperson has ever noticed.

| Concern | Hand-rolled wp\_remote\_request | Webhook Actions |
| --- | --- | --- |
| Pipedrive connector | None — you write the three calls | Also none. It delivers a mapped payload to a URL you name; the person and lead logic still lives at the receiving end or in a chain step |
| Delivery timing | Inline — the visitor waits for three round trips | Queued — the request returns before the first call |
| A 429 from the burst window | Lost unless you wrote the wait | Retried with exponential backoff, 5 attempts, capped at an hour |
| A 400 from a bad field | Retried forever if you loop naively | Marked failed at once — a bad payload is not retried |
| Evidence of what was sent | Whatever you remembered to log | Per-attempt request and response, with replay |
| The API token | A constant in wp-config or a plugin option | Encrypted in the Credentials Vault, referenced by id, never returned to any caller |

The honest read of that table: the right-hand column is not a Pipedrive integration off a shelf. There is no connector catalogue, and the search-then-create sequence is still yours to design, either as a chain of steps or at the endpoint that receives the payload. What it removes is the queue, the backoff curve, the attempt log and the secret storage, which is the part that takes a week and the part people skip.

The secret row is the one worth spelling out, and Pipedrive is the easy case. A per-user API token is a static value in a header you name, which is exactly the shape the plugin's **Credentials Vault** holds: you add it once on the Credentials Vault screen, or with a `POST` to `/wp-json/fswa/v1/credentials`, pick the API key type with `x-api-token` as the header name, and the webhook then references it by id. The value is encrypted at rest, injected only at dispatch and redacted out of the delivery log, and it never comes back over the API — a read returns a masked hint, so the token is absent from the webhook config, the export file and anything an AI assistant can see. A CRM that authenticates with an OAuth exchange rather than a static token, [Zoho for instance](https://wpwebhooks.org/blog/wordpress-zoho-crm-integration/), does not get this for free.

try\_it

Seeing it run beats reading about it. The live preview boots a throwaway WordPress with Webhook Actions already installed and demo deliveries sitting in the log — no signup, nothing left on your machine afterwards.

[Try the live preview →](https://playground.wordpress.net/?blueprint-url=https://wpwebhooks.org/blueprint.json) [Install plugin](https://downloads.wordpress.org/plugin/flowsystems-webhook-actions.zip)

/ Exposure

## What does Pipedrive not protect you from?

Three things, and none of them show up in a successful test.

**The token is a person, not a service.** There is no service account in the API-token model. The token inherits that user's visibility and permissions in full, and it dies when the user is deactivated. Create a dedicated integration user, give it the permission set it needs and nothing more, and set `owner_id` explicitly so web leads land with the right rep rather than with the integration user.

**A public form is an unauthenticated write path into the CRM.** Anything that turns a submission into a person and a lead has handed the internet a way to create both, and each attempt spends 60 tokens of a budget the sales team shares. Spam does not just create junk records; at volume it exhausts the daily budget and every other integration on the account starts receiving `429`s. Gate the form before the queue, not after.

**Retries multiply leads, not just persons.** The search makes the person call idempotent. Nothing makes the lead call idempotent, so a delivery that succeeded but timed out on the response, then retried, produces two leads for one enquiry. Store the lead id on the WordPress side when you get it, and make the retry check for it first.

If the destination is a different CRM, the shape is the same and the traps differ: [Salesforce meters calls per org on a rolling day](https://wpwebhooks.org/blog/wordpress-salesforce-integration/), [HubSpot limits requests per ten seconds](https://wpwebhooks.org/blog/gravity-forms-hubspot-integration/), and [Zoho CRM charges credits per ten records](https://wpwebhooks.org/blog/wordpress-zoho-crm-integration/). What they share is the advice in the previous section: never make the call where the visitor is waiting.

/Footnotes

¹ Authentication, [Pipedrive Developer Documentation](https://pipedrive.readme.io/docs/core-api-concepts-authentication) — the x-api-token header, the one-active-token rule, and the company-domain base URL.

² Rate limiting, [Pipedrive Developer Documentation](https://pipedrive.readme.io/docs/core-api-concepts-rate-limiting) — the daily token budget formula, plan multipliers, burst limits per two-second window, and the per-operation token costs. Read 2026-09-10.

³ Persons and Leads endpoint references, [developers.pipedrive.com](https://developers.pipedrive.com/docs/api/v1/Persons).

⁴ [LeadBooster Chatbot by Pipedrive](https://wordpress.org/plugins/leadbooster-by-pipedrive/) on WordPress.org — the only plugin published by Pipedrive itself.

## Structured data

```json
{"@context":"https://schema.org","@type":"Article","headline":"WordPress Pipedrive Integration: API, Token and Limits","description":"A WordPress Pipedrive integration on the REST API: the x-api-token header, search-then-create for persons and leads, and the token budget behind every call.","datePublished":"2026-09-10","dateModified":"2026-09-10","author":{"@type":"Person","name":"Mateusz Skorupa","url":"https://wpwebhooks.org/about/"},"publisher":{"@type":"Organization","name":"WP Webhooks","url":"https://wpwebhooks.org"},"url":"https://wpwebhooks.org/blog/wordpress-pipedrive-integration/","image":{"@type":"ImageObject","url":"https://wpwebhooks.org/blog/wordpress-pipedrive-integration/og_image.jpg","width":1200,"height":630,"caption":"Cyberpunk illustration of two mismatched figures hauling on separate levers in a bank of heavy interlocked hand levers, the nearest one looking down the frame towards the other lever rather than at his own hands while a counter wheel runs down beside him."},"keywords":["wordpress pipedrive integration","pipedrive wordpress","wordpress to pipedrive","pipedrive api wordpress","pipedrive wordpress plugin"]}

{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"WP Webhooks","item":"https://wpwebhooks.org/"},{"@type":"ListItem","position":2,"name":"Blog","item":"https://wpwebhooks.org/blog/"},{"@type":"ListItem","position":3,"name":"WordPress Pipedrive Integration: API, Token and Limits","item":"https://wpwebhooks.org/blog/wordpress-pipedrive-integration/"}]}

{"@context":"https://schema.org","@type":"FAQPage","mainEntity":[{"@type":"Question","name":"Is there an official Pipedrive plugin for WordPress?","acceptedAnswer":{"@type":"Answer","text":"One: the LeadBooster Chatbot by Pipedrive on WordPress.org, which embeds the Pipedrive chatbot and turns conversations into deals. It requires the paid LeadBooster add-on and captures only what the chatbot asks. It does not watch forms, orders or registrations, so those events need the REST API or a third-party connector."}},{"@type":"Question","name":"How does a WordPress site authenticate to the Pipedrive API?","acceptedAnswer":{"@type":"Answer","text":"With a per-user API token sent in the x-api-token request header, against a base URL that includes the company subdomain. The token is tied to one user and company, and only one active token exists per user, so regenerating it stops every integration using the old one. OAuth 2.0 is the path for apps listed on the Pipedrive Marketplace."}},{"@type":"Question","name":"Should a WordPress form create a Pipedrive person, lead or deal?","acceptedAnswer":{"@type":"Answer","text":"A person and then a lead. A lead is an unqualified opportunity in the Leads Inbox, and POST /api/v1/leads requires a title plus a person_id or organization_id, so the person must exist first. Search persons by email with exact_match before creating one, so a repeated submission attaches to the existing person instead of duplicating it."}},{"@type":"Question","name":"What are the Pipedrive API rate limits?","acceptedAnswer":{"@type":"Answer","text":"Two limits, both answered with a 429. A daily token budget of 30,000 base tokens times a plan multiplier (Lite 1, Growth 2, Premium 5, Ultimate 7) times the number of seats. And a burst limit per two-second window: 20 requests on Lite, 40 on Growth, 100 on Premium, 120 on Ultimate for API-token requests, with search capped at 10 per two seconds on every plan."}},{"@type":"Question","name":"How many tokens does creating a Pipedrive lead cost?","acceptedAnswer":{"@type":"Answer","text":"Pipedrive publishes costs for some operations: a search costs 40 tokens, an update 10, a single read 2. The create cost is not in the published table, so budget it at the update figure. On that basis a new web lead costs about 60 tokens for the search, person and lead calls, which is 500 leads a day on a one-seat Lite account before anything else uses the API."}}]}

{"@context":"https://schema.org","@type":"ImageObject","contentUrl":"https://wpwebhooks.org/diagrams/wordpress-pipedrive-integration.png","caption":"FIG 01 — Search first, then create: the two-call shape that keeps Pipedrive free of duplicates","description":"A WordPress hook fires and the delivery is queued rather than sent inline. The worker first searches the persons endpoint by email with exact matching. If a person exists, its id is reused; if not, a person is created with the email and phone arrays the v2 API expects. The worker then creates a lead that references the person id. Both writes draw from a daily token budget that Pipedrive computes from plan and seat count, and every call also counts against a burst limit measured over two-second windows. A 429 from either limit is worth retrying later; a 400 from a bad field is not.","encodingFormat":"image/png","creator":{"@type":"Organization","name":"WP Webhooks","url":"https://wpwebhooks.org/"},"copyrightHolder":{"@type":"Organization","name":"Flow Systems","url":"https://flowsystems.pl/"},"copyrightNotice":"© Flow Systems","creditText":"WP Webhooks","license":"https://creativecommons.org/licenses/by/4.0/","acquireLicensePage":"https://wpwebhooks.org/image-license/"}
```