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

# Pipedrive

> Client-mode REST API connector for Pipedrive CRM (API v2 + v1): open and move deals, log activities and notes from plant alarms, update organization custom fields, search persons, create leads, register webhooks

Technical Preview

## Overview

A client-mode connector for the [Pipedrive API](https://developers.pipedrive.com/docs/api/v1) that turns plant events into sales and service follow-ups. A machine alarm can open a deal or an activity, add a note, and close the activity when the alarm clears. Counters from the installed base can be written to organization custom fields.

The connector uses API v2 (`/api/v2/...`) for deals, activities, organizations, persons, pipelines, stages and deal fields, and v1 (`/v1/...`) only for notes, leads, webhooks and the current user, which have no v2 version yet. Topics use `crm/pipedrive/<object>/<verb>`; each response is published on `<source topic>/response`.

> [!NOTE]
>
> The template was checked against Pipedrive's published OpenAPI files and a local mock, and `api.pipedrive.com` was probed live with an invalid token (401, as expected). It has **not** been run against a real Pipedrive company yet, so status stays blocked until an authenticated smoke passes.

## Authentication

Create a personal API token in Pipedrive under **Settings > Personal preferences > API**. The connector sends it in the `x-api-token` header, taken from the `api_token` field of each MQTT payload.

> [!WARNING]
>
> Do not publish the token in retained messages. Store it as a broker secret (for example `PIPEDRIVE_API_TOKEN`) and have a LoT action add it to the payload with `GET SECRET` before publishing to the connector topic.

For a Marketplace (OAuth) app, change the header to `Authorization: Bearer <access_token>` and set `BASE_ADDRESS` to the `api_domain` returned by `https://oauth.pipedrive.com/oauth/token` (for example `https://yourcompany.pipedrive.com`).

## Payload fields

| Field | Used by | Notes |
| - | - | - |
| `api_token` | every event | Pipedrive API token |
| `id` | `...Get`, `...Update` | Numeric id of the deal, activity or organization |
| `query` | list and search events | URL-encoded query string; send `""` for none. Search needs `term=` (at least 2 characters) |
| `body` | create and update events | JSON object sent as the request body |

## Events

| Event | Method | Endpoint | Source topic | Write |
| - | - | - | - | - |
| `CurrentUser` | `GET` | `/v1/users/me` | `crm/pipedrive/users/me/get` | |
| `DealsList` | `GET` | `/api/v2/deals?{query}` | `crm/pipedrive/deals/list` | |
| `DealGet` | `GET` | `/api/v2/deals/{id}` | `crm/pipedrive/deals/get` | |
| `DealsSearch` | `GET` | `/api/v2/deals/search?{query}` | `crm/pipedrive/deals/search` | |
| `DealCreate` | `POST` | `/api/v2/deals` | `crm/pipedrive/deals/create` | yes |
| `DealUpdate` | `PATCH` | `/api/v2/deals/{id}` | `crm/pipedrive/deals/update` | yes |
| `ActivitiesList` | `GET` | `/api/v2/activities?{query}` | `crm/pipedrive/activities/list` | |
| `ActivityCreate` | `POST` | `/api/v2/activities` | `crm/pipedrive/activities/create` | yes |
| `ActivityUpdate` | `PATCH` | `/api/v2/activities/{id}` | `crm/pipedrive/activities/update` | yes |
| `OrganizationsList` | `GET` | `/api/v2/organizations?{query}` | `crm/pipedrive/organizations/list` | |
| `OrganizationGet` | `GET` | `/api/v2/organizations/{id}` | `crm/pipedrive/organizations/get` | |
| `OrganizationCreate` | `POST` | `/api/v2/organizations` | `crm/pipedrive/organizations/create` | yes |
| `OrganizationUpdate` | `PATCH` | `/api/v2/organizations/{id}` | `crm/pipedrive/organizations/update` | yes |
| `PersonsSearch` | `GET` | `/api/v2/persons/search?{query}` | `crm/pipedrive/persons/search` | |
| `PersonCreate` | `POST` | `/api/v2/persons` | `crm/pipedrive/persons/create` | yes |
| `PipelinesList` | `GET` | `/api/v2/pipelines?{query}` | `crm/pipedrive/pipelines/list` | |
| `StagesList` | `GET` | `/api/v2/stages?{query}` | `crm/pipedrive/stages/list` | |
| `DealFieldsList` | `GET` | `/api/v2/dealFields?{query}` | `crm/pipedrive/dealfields/list` | |
| `NoteCreate` | `POST` | `/v1/notes` | `crm/pipedrive/notes/create` | yes |
| `LeadCreate` | `POST` | `/v1/leads` | `crm/pipedrive/leads/create` | yes |
| `WebhooksList` | `GET` | `/v1/webhooks` | `crm/pipedrive/webhooks/list` | |
| `WebhookCreate` | `POST` | `/v1/webhooks` | `crm/pipedrive/webhooks/create` | yes |

`OrganizationUpdate` covers the catalog's `PUT organizations/{id}`: in API v2 updates use `PATCH`, and v1 organization endpoints are no longer in Pipedrive's v1 spec. No `DELETE` events are included on purpose.

## Basic Syntax

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
DEFINE ROUTE PipedriveRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.pipedrive.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT CurrentUser
        WITH SOURCE_TOPIC "crm/pipedrive/users/me/get"
        WITH DESTINATION_TOPIC "crm/pipedrive/users/me/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/users/me"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT DealsList
        WITH SOURCE_TOPIC "crm/pipedrive/deals/list"
        WITH DESTINATION_TOPIC "crm/pipedrive/deals/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/deals?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT DealGet
        WITH SOURCE_TOPIC "crm/pipedrive/deals/get"
        WITH DESTINATION_TOPIC "crm/pipedrive/deals/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/deals/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT DealsSearch
        WITH SOURCE_TOPIC "crm/pipedrive/deals/search"
        WITH DESTINATION_TOPIC "crm/pipedrive/deals/search/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/deals/search?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT DealCreate
        WITH SOURCE_TOPIC "crm/pipedrive/deals/create"
        WITH DESTINATION_TOPIC "crm/pipedrive/deals/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/deals"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT DealUpdate
        WITH SOURCE_TOPIC "crm/pipedrive/deals/update"
        WITH DESTINATION_TOPIC "crm/pipedrive/deals/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/v2/deals/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ActivitiesList
        WITH SOURCE_TOPIC "crm/pipedrive/activities/list"
        WITH DESTINATION_TOPIC "crm/pipedrive/activities/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/activities?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT ActivityCreate
        WITH SOURCE_TOPIC "crm/pipedrive/activities/create"
        WITH DESTINATION_TOPIC "crm/pipedrive/activities/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/activities"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ActivityUpdate
        WITH SOURCE_TOPIC "crm/pipedrive/activities/update"
        WITH DESTINATION_TOPIC "crm/pipedrive/activities/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/v2/activities/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT OrganizationsList
        WITH SOURCE_TOPIC "crm/pipedrive/organizations/list"
        WITH DESTINATION_TOPIC "crm/pipedrive/organizations/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/organizations?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT OrganizationGet
        WITH SOURCE_TOPIC "crm/pipedrive/organizations/get"
        WITH DESTINATION_TOPIC "crm/pipedrive/organizations/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/organizations/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT OrganizationCreate
        WITH SOURCE_TOPIC "crm/pipedrive/organizations/create"
        WITH DESTINATION_TOPIC "crm/pipedrive/organizations/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/organizations"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT OrganizationUpdate
        WITH SOURCE_TOPIC "crm/pipedrive/organizations/update"
        WITH DESTINATION_TOPIC "crm/pipedrive/organizations/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/v2/organizations/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT PersonsSearch
        WITH SOURCE_TOPIC "crm/pipedrive/persons/search"
        WITH DESTINATION_TOPIC "crm/pipedrive/persons/search/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/persons/search?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT PersonCreate
        WITH SOURCE_TOPIC "crm/pipedrive/persons/create"
        WITH DESTINATION_TOPIC "crm/pipedrive/persons/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/persons"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT PipelinesList
        WITH SOURCE_TOPIC "crm/pipedrive/pipelines/list"
        WITH DESTINATION_TOPIC "crm/pipedrive/pipelines/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/pipelines?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT StagesList
        WITH SOURCE_TOPIC "crm/pipedrive/stages/list"
        WITH DESTINATION_TOPIC "crm/pipedrive/stages/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/stages?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT DealFieldsList
        WITH SOURCE_TOPIC "crm/pipedrive/dealfields/list"
        WITH DESTINATION_TOPIC "crm/pipedrive/dealfields/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/dealFields?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT NoteCreate
        WITH SOURCE_TOPIC "crm/pipedrive/notes/create"
        WITH DESTINATION_TOPIC "crm/pipedrive/notes/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/notes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT LeadCreate
        WITH SOURCE_TOPIC "crm/pipedrive/leads/create"
        WITH DESTINATION_TOPIC "crm/pipedrive/leads/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/leads"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT WebhooksList
        WITH SOURCE_TOPIC "crm/pipedrive/webhooks/list"
        WITH DESTINATION_TOPIC "crm/pipedrive/webhooks/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/webhooks"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT WebhookCreate
        WITH SOURCE_TOPIC "crm/pipedrive/webhooks/create"
        WITH DESTINATION_TOPIC "crm/pipedrive/webhooks/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/webhooks"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

## Examples

**Activity from an alarm**

Publish to `crm/pipedrive/activities/create`:

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{"api_token": "<from GET SECRET>", "body": {"subject": "Check press 7 overtemperature", "type": "task", "due_date": "2026-10-06", "deal_id": 42}}
```

When the alarm clears, publish `{"api_token": "...", "id": <activity id>, "body": {"done": true}}` to `crm/pipedrive/activities/update`.

**Open deals in a pipeline**

Publish to `crm/pipedrive/deals/list`:

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{"api_token": "<from GET SECRET>", "query": "status=open&pipeline_id=1&limit=50"}
```

v2 lists page with a cursor: pass `cursor=<additional_data.next_cursor>` in `query` for the next page.

**Organization custom field**

Get the field key from Pipedrive's organization fields (`GET /api/v2/organizationFields`, not packaged as an event), then publish to `crm/pipedrive/organizations/update`:

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{"api_token": "<from GET SECRET>", "id": 7, "body": {"custom_fields": {"<field key>": 1280}}}
```

## Webhooks into the broker

`WebhookCreate` registers a Pipedrive webhook (`version` `"2.0"`, `event_action` such as `create` / `change` / `delete` / `*`, `event_object` such as `deal` / `activity` / `organization`). Pipedrive then POSTs each change to `subscription_url`. To receive it, run a separate server-mode connector and protect it with the webhook's `http_auth_user` / `http_auth_password`:

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
DEFINE ROUTE PipedriveWebhookReceiver WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_SERVER "true"
        WITH SERVER_PORT '8443'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT PipedriveChange
        WITH ENDPOINT "/pipedrive/webhook"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "crm/pipedrive/webhook/events"
```

The receiver must be reachable from the internet over HTTPS. It is not part of the client template.

## Rate limits

Pipedrive gives each company a daily token budget, and every call spends tokens (the OpenAPI `x-token-cost`: 1 for a GET by id, 5 to 10 for lists, 20 for search, 5 for v2 writes, 10 for v1 writes). Short burst limits also apply, and excess calls get `429`. Responses carry `X-RateLimit-*` and `X-Daily-RateLimit-Token-*` headers. Avoid polling lists from fast timers; react to events or use webhooks instead.

## Testing

| Check | Result |
| - | - |
| Every event matches the Pipedrive OpenAPI (method, path, JSON body) | 22/22 |
| Local mock round-trip | 22/22 |
| Live probe with an invalid token | 401 as expected |
| Live call with a real token | Not run yet |

To finish the check, set `PIPEDRIVE_API_TOKEN` and run `python3 smoke_pipedrive.py --live` from the package, then deploy the connector and publish `{"api_token": "..."}` to `crm/pipedrive/users/me/get`.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps/index)
* [Pipedrive API reference](https://developers.pipedrive.com/docs/api/v1)


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