Website form to Pipedrive: store first, match by email, create a linked lead, respect the limits

The sequence

A reliable form handler does its work in a fixed order. It validates the submission and saves it in your own database with a reference of its own and a pending status. It then claims the submission so only one worker sends it. It looks for an existing person by email; if none exists it creates one; and finally it creates a lead linked to that person, with the submission's reference stored on the lead. Pipedrive's documentation says a lead must be linked to a person or an organisation, and that a person needs only a name, with emails given as a list of value, primary flag and label. Only after the lead is created does the saved submission become delivered.

• Saving first means an outage cannot lose the enquiry.
• The visitor's page should not wait for Pipedrive.
• Put the submission's reference on the lead, in a custom lead field an administrator creates (leads inherit the custom fields of deals) or, failing that, in the lead title, so the lead can be found again.
• Pipedrive's lead documentation shows no idempotency key or duplicate protection, so the reference is for looking up a lead, not for making a repeat safe.
• Lead search covers title, notes and custom fields, but Pipedrive's page does not say which custom field types, so prove the lookup against your real test account before relying on it.

Which API version to build against

Pipedrive's documentation now shows the person calls as API v2: adding a person is POST /api/v2/persons and searching persons is GET /api/v2/persons/search. Its changelog, announced on 29 July 2026, says the deprecated v1 endpoints, including POST /v1/persons and GET /v1/persons/search, are out of support from 1 August 2026: they may still respond, but Pipedrive gives no maintenance, bug fixes or availability guarantees and may change or remove them without notice. Adding a lead is still POST /api/v1/leads, with no v2 equivalent shown on the leads page when it was checked on 11 October 2026, and the changelog list contains no leads endpoints; lead search is GET /api/v2/leads/search. So a new build uses v2 for people and v1 for creating a lead, and re-reads the leads page before relying on that. The rate-limit page also says v2 endpoints cost fewer tokens than v1.

• Write down each endpoint and version the client uses, in one module, so a change is one edit.
• Check Pipedrive's changelog when you next touch the integration; a v1 lead endpoint could be announced later.
• Do not copy older tutorials that use the v1 persons paths.

Matching by email, and its limits

Person search accepts a term, a list of fields to search and an exact-match option, so a search on the email field with exact match finds people with that address. It cannot make duplicates impossible: two people already sharing an address may both match, and two simultaneous submissions can both find nothing. Handle the second case by delivering one submission at a time for any one email address, and by keeping the Pipedrive person id against the email once you have it. When more than one person matches, flag the submission for a human decision instead of picking one. Cleaning existing duplicates is a separate data task.

• Decide in advance what a repeat enquiry does: a new lead on the same person, a note, or a review.
• Search calls use more of the rate budget than a plain fetch.
• Normalise the email's case and whitespace before searching.

Know the limits

Pipedrive gives each account a daily token budget shared by all users and integrations, resetting at midnight in the server's time zone, and applies burst limits per token over a rolling two seconds. Search has its own flat cap and costs more of the budget than fetching one item. When the budget is exhausted, requests are rejected with 429 until the reset, and the documentation warns that continuing heavy token traffic after 429s can lead to a block with a 403 page. Response headers report the remaining capacity, and the rate-limit page lists using webhooks among the ways to reduce pressure on the limits.

• A small form rarely threatens the budget, but other integrations share it.
• On 429, stop for the stated time; do not loop.
• Track the headers if volume grows.

Design for the outage

The saved submission has these states: pending, sending, delivered and needs attention. A delivery job claims a pending item, so two workers cannot send it, and waits as asked on 429. A 429 means Pipedrive rejected the call before acting, so retrying after the wait is safe. A timeout, a dropped connection or a server error is different: the lead may have been created and the reply lost. Pipedrive documents no idempotency for creating a lead, so a blind retry can create a second lead. Before any retry after such an unknown outcome, search for the lead by the submission's reference. If it is found, mark the item delivered; if it is not found, retry the create; if the search itself cannot be made, mark the item as needing attention for a person and do not retry. A rejected credential should not be retried either; it should alert the person who holds the Pipedrive administrator rights. After the fix, one run resolves the item. Keep the credential in server configuration and never in the page.

• Show the owner a count of items that need attention.
• Never show the visitor an error for a CRM fault.
• Test with a stand-in that returns 429 and 503, that creates a lead and then drops the reply, that refuses the lookup, and that rejects the credential.
• Keep a reconciliation check that lists delivered submissions with no lead, or with more than one lead, because this design lowers the chance of a duplicate and cannot remove it.

How the paid outcome is accepted

The Pipedrive outcome is accepted when a test submission creates one person and one linked lead, a repeat reuses the person and adds one lead under your rule, a 429 is delivered after the wait, a lead created with a lost reply is found by its reference and not created twice, an unavailable lookup flags the item instead of retrying, the reconciliation check lists seeded problems, and no credential appears in page source or logs. It does not promise that a duplicate can never occur. The fixed £345 test price is untested and payment follows your sign-off. Other CRMs, duplicate cleaning and consent wording are outside it. For HubSpot, the job that stops form duplicates in HubSpot and the one that repairs the form-to-salesperson path are the neighbours.