> ## Documentation Index
> Fetch the complete documentation index at: /help/llms.txt
> Use this file to discover all available pages before exploring further.

# Pipedrive

> Create Pipedrive persons and deals when LinkedIn contacts reply, and stop follow-ups when a deal is won or lost.

> [!NOTE]
>
> **Pro plan.** Pipedrive works through a connection, HTTP steps and listeners (**Wait for webhook**, **Call & wait**), which are part of Pro and Agency (and the free trial). Anything you already have keeps working on every plan. See [Plans and billing](/help/account/billing.md).

When a contact replies on LinkedIn, Kerux creates the person and a deal in Pipedrive with two **Webhook / HTTP** steps. When the deal is won or lost in Pipedrive, a Pipedrive webhook tells Kerux and the contact takes the matching path.

> [!NOTE]
>
> **How it connects:** through Pipedrive's API with your API token, and Pipedrive webhooks (no app to install). See [Pipedrive's Persons](https://developers.pipedrive.com/docs/api/v1/Persons) and [Deals](https://developers.pipedrive.com/docs/api/v1/Deals) API docs and its [authentication guide](https://pipedrive.readme.io/docs/core-api-concepts-authentication). The requests and answers below follow Pipedrive's docs.

## Before you start

* **Pipedrive plan:** Pipedrive says every plan has an API token.
* **Your API token:** in Pipedrive, open **Settings > Personal preferences > API** and copy it.
* **Your company domain:** the part before `.pipedrive.com` in your Pipedrive address.

## 1. Connect Pipedrive

In Kerux, open **Integrations > Connections**, click **Connect** on **Custom API** (under **Developers**):

* **How it signs in:** **API key in a header**, **Header name** `x-api-token`, paste the token.
* **Base URL:** `https://YOUR-COMPANY.pipedrive.com`

Click **Save**, then **Test connection**.

## 2. Run the steps when the contact replies

A contact who replies leaves the campaign (the **When the contact replies** box). In that box, add the action **Send to another campaign** and pick a short campaign, for example "Replied: to Pipedrive". Its steps run for every contact who replies.

### Create the person

Add a **Webhook / HTTP** step, pick the Pipedrive connection and name it `person`. Paste this in the step's JSON:

```json theme={null}
{
  "method": "POST",
  "url": "/api/v2/persons",
  "bodyType": "json",
  "body": {
    "name": "{{contact.full_name}}",
    "emails": [{ "value": "{{email}}", "primary": true, "label": "work" }]
  }
}
```

Pipedrive answers with the new person (from its docs, trimmed):

```json theme={null}
{ "success": true, "data": { "id": 1203, "name": "Maria Lopez" } }
```

### Create the deal

Add a second **Webhook / HTTP** step named `deal`. Pipedrive's ids are numbers, so this body is sent as text, which keeps the id unquoted:

```json theme={null}
{
  "method": "POST",
  "url": "/api/v2/deals",
  "headers": { "content-type": "application/json" },
  "bodyType": "text",
  "body": "\\{\"title\": \"{{contact.company}} - LinkedIn\", \"person_id\": {{steps.person.response.body.data.id}}\\}"
}
```

In a text body, a single `{` or `}` would be read as a choice between words (spintax), so the JSON braces are written `\{` and `\}` (here doubled, `\\{`, because the body sits inside the step's JSON). The double braces of variables stay as they are.

You can also send `owner_id`, `org_id`, `pipeline_id`, `stage_id` and `value` (Pipedrive's field names). The deal id is `{{steps.deal.response.body.data.id}}`.

To keep the LinkedIn profile on the person, create a custom field in Pipedrive and send it under its key, as Pipedrive's docs describe for custom fields.

## 3. Hear back when the deal is won or lost

**1. Add a Wait for webhook step**

After the deal step, add **Wait for webhook**, choose **One shared URL + a match rule** and match the deal id in Pipedrive's payload to `{{steps.deal.response.body.data.id}}`. Click **Listen for test event**.

**2. Add the webhook in Pipedrive**

In Pipedrive, open **Tools and apps > Webhooks**, create a webhook for deal updates and paste the Kerux URL. Change a test deal so Kerux receives a sample, then pick the deal id and status fields from it.

**3. Branch on the status**

Add a **Condition** on the status field from the sample: won goes to a thank-you message, lost to a tag and the end.

## Test with one contact

In the follow-up campaign's **Builder**, click **Test** to open **Test on one contact**. The contact's journey shows both requests and Pipedrive's answers. Check the person and the deal in Pipedrive.

## Common errors

> [accordion] 401 or 403 from Pipedrive
>
> The token is wrong or belongs to a user without access. Copy it again from **Personal preferences > API**, edit the connection and paste it.

> [accordion] The deal has no person
>
> The deal step ran before the person step had an answer, or the name in `steps.` doesn't match the step's name. Name the first step `person` and use `{{steps.person.response.body.data.id}}`.

> [accordion] Same person twice in Pipedrive
>
> Pipedrive's create endpoint doesn't check for duplicates. Search first (Pipedrive's person search endpoint) and branch, or merge in Pipedrive.

Related: [Webhook steps](/help/integrations/webhook-steps.md), [Meetings booked by contacts](/help/campaigns/meetings.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.