Sending WordPress Events to Pipedrive as Persons and Leads

/ Official

Is there an official Pipedrive WordPress plugin?

One, and it does something narrower than the phrase suggests. Pipedrive publishes the LeadBooster Chatbot 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 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 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".

/ 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 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 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:

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.

/ 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.

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, does not get this for free.

/ 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 429s. 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, HubSpot limits requests per ten seconds, and Zoho CRM charges credits per ten records. What they share is the advice in the previous section: never make the call where the visitor is waiting.