Pipedrive
Start agents when deals, leads, people, organizations, activities, or notes change in Pipedrive, and add their results as notes.
On this page
| Modes | Inbound, outbound |
| YAML type | pipedrive |
| Credentials | A Connection of type pipedrive, with the company domain and a user's API token |
| Bridge | Not supported |
| Custom domain | Not supported |
| Linked agents | One or more. A matching event starts every linked agent. |
| While paused | Events get 200 and start no runs. Outbound sends nothing. |
Set up
In Pipedrive, open your account name at the top right, then Company settings → Personal preferences → API, and copy the API token. Connectors act as the token's user; see API token and user.
In connic, open Project Settings → Connections, click New connection, and choose Pipedrive. You can also create the Connection from the Connection picker in the connector form. Enter a Name, the Company domain, the part before
.pipedrive.comin your Pipedrive address, and the API token. Click Create connection.Open the agent. In Connector Flow, click Add inbound connector for record events or Add outbound connector for notes. Then click Create New Connector and choose Pipedrive.
Choose the mode, Inbound (Record events) or Outbound (Notes), and pick the Connection under Connection. For inbound, pick the Records and the Event. Click Create. An inbound connector registers its webhook in Pipedrive now, and an outbound connector checks the API token. For outbound, then choose how the agent uses the connector and click Link connector.
Configuration
The fields of a Pipedrive connector, the same in connectors/*.yaml, the REST API, and connic MCP. The descriptions name the matching setting in the dashboard. Connectors in code describes the fields every connector shares, such as agents and environments.
| Field | Type | Status | Description |
|---|---|---|---|
| type | string | Required | pipedrive. |
| mode | string | Required | inbound or outbound. Dashboard: Mode. |
| connection | string | Required | Inbound and outbound. Name or ID of a Pipedrive Connection. Dashboard: Connection. |
| config | object | Optional | Pipedrive settings. Outbound connectors have none. |
| record_type | string | Optional | Inbound. The records whose changes start runs: deal, lead, person, organization, activity, or note. Dashboard: Records.Default: deal |
| action | string | Optional | Inbound. create, change, delete, or any for all three. Dashboard: Event.Default: create |
| ignore_api_changes | boolean | Optional | Inbound. Skips changes made through the Pipedrive API, which include the notes your agents add, so they don't start new runs. Turn it off to also react to changes other integrations make. Dashboard: Ignore API changes.Default: true |
The company domain and the API token belong to the Connection, not to the connector.
Generated values
connic sets these when you save the connector.
| Value | Modes | Description |
|---|---|---|
| Webhook | Inbound | The connector's webhook in Pipedrive. connic registers it when you save the connector, so you don't create it in Pipedrive. |
| Webhook password | Inbound | The HTTP basic auth password Pipedrive sends with every delivery, which connic checks. |
Agent input
Modes: Inbound
An inbound connector starts a run for every linked agent each time a record of its type is created, updated, or deleted, as its event says. The run receives:
{
"event": "deal.create",
"record_type": "deal",
"action": "create",
"record_id": "128",
"title": "Acme rollout",
"url": "https://acme.pipedrive.com/deal/128",
"user_id": "1043",
"change_source": "app",
"conversation_id": "pipedrive:acme/deal/128",
"raw": { ... }
}eventjoinsrecord_typeandaction, which iscreate,change, ordelete.record_idis the record's ID in Pipedrive, a UUID for leads, andtitlethe deal or lead title, the person's or organization's name, or the activity's subject.urllinks to deals, leads, people, and organizations in Pipedrive, and is empty for deleted records.user_idis the Pipedrive user who made the change, andchange_sourceisapporapi.conversation_idstays the same for every event of one record. To give the agent the earlier events as history, setsession.key: input.conversation_idin its YAML; the connector doesn't turn on sessions by itself.rawis Pipedrive's full webhook payload as sent:dataholds the record,previousthe old values of changed fields or, for deletions, the deleted record, andmetathe event details.
A delivery Pipedrive retries for the same event doesn't start another run. Inbound mode doesn't reply by itself: to add a note, link the agent to an outbound Pipedrive connector that uses the same Connection; see Outbound delivery.
API token and user
An API token acts as the Pipedrive user it belongs to. Notes from your agents show that user as their author, and the connector's webhook sends only the records that user can see. Each user has one token per company, and creating a new token in Pipedrive replaces the old one: then enter the new token on the Connection. A Pipedrive user just for your agents keeps their notes apart from a person's.
With ignore_api_changes on, changes made through the Pipedrive API start no runs, whoever made them. That includes the notes outbound connectors add, so agents don't trigger themselves.
Pipedrive webhook
Modes: Inbound
Saving an inbound connector registers a webhook in Pipedrive for its records and event. Each connector has its own webhook, so several connectors can watch the same records, for example one per environment. You find the webhooks in Pipedrive under Settings → Tools and apps → Webhooks.
Pipedrive doesn't sign webhooks. connic generates an HTTP basic auth password for each webhook and checks it on every delivery. Changing the records, the event, or the Connection registers a new webhook and removes the old one. Saving the connector also registers a new webhook when Pipedrive deleted the old one. Deleting the connector removes its webhook.
Outbound delivery
Modes: Outbound
An outbound Pipedrive connector adds one note each time it's used: when a linked agent's run completes, when the model calls it as a tool, or when middleware calls it, depending on the link's usage. The first rule that applies decides where:
- When the output or payload sets
deal_id,lead_id,person_id, ororg_id, the note goes to those records. One note can belong to several of them. - When the run came in through a Pipedrive inbound connector on the same Connection, the note goes to the deal, lead, person, or organization the run started from. For an activity or note, it goes to the record that activity or note belongs to.
- Otherwise the delivery fails, as does a run that started from a deleted record.
Automatic output
An automatic link adds the run's final output. Plain text becomes the note. A JSON object takes the text from body, text, message, response, or output, in that order, and can set the record IDs. The note keeps the text's paragraphs and line breaks.
{
"body": "Acme runs 40 seats today and asked about SSO.\n\nNext step: send the security overview before Friday."
}Agent-tool and middleware payload
The model or middleware passes body, which is required and can't be empty, and optionally deal_id, lead_id, person_id, and org_id. Lead IDs are UUIDs, the others whole numbers. Other fields are rejected.
{
"body": "Follow-up call booked for Thursday.",
"deal_id": 128
}Delivery and retries
When Pipedrive rate-limits a note, connic waits and sends it again. The connector's runs show each delivery with the note's ID and records, or with the error.
Limits and errors
| Limit | Value |
|---|---|
| Answer to Pipedrive | Pipedrive waits 10 seconds for an answer. connic answers right away and runs the agents afterwards. |
| Failed deliveries | Pipedrive tries a delivery three more times, after 3, 30, and 150 seconds. |
| Blocked webhook | After 10 deliveries that fail on the first try, Pipedrive blocks the webhook for 30 minutes and drops its events in that time. |
| Removed webhook | Pipedrive deletes a webhook that has no successful delivery for 3 days in a row. Save the connector again to register a new one. |
| Webhooks per user | 40 for each Pipedrive user, counting every inbound connector that uses the user's API token. |
| API requests | Pipedrive limits requests per API token and per day, depending on the plan. When Pipedrive rate-limits a note, connic waits and sends it again. |
| Note size | About 100,000 characters. |
Requests with missing or wrong credentials get 401. Saving a connector fails when Pipedrive rejects the company domain or the API token, or when the token's user can't create another webhook. A delivery fails when Pipedrive rejects the note, for example when the record doesn't exist or the token's user can't see it.