Skip to main content
connic
Connectors

Pipedrive

Start agents when deals, leads, people, organizations, activities, or notes change in Pipedrive, and add their results as notes.

Last updated
ModesInbound, outbound
YAML typepipedrive
CredentialsA Connection of type pipedrive, with the company domain and a user's API token
BridgeNot supported
Custom domainNot supported
Linked agentsOne or more. A matching event starts every linked agent.
While pausedEvents get 200 and start no runs. Outbound sends nothing.

Set up

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

  2. 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.com in your Pipedrive address, and the API token. Click Create connection.

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

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

FieldTypeStatusDescription
typestringRequiredpipedrive.
modestringRequiredinbound or outbound. Dashboard: Mode.
connectionstringRequiredInbound and outbound. Name or ID of a Pipedrive Connection. Dashboard: Connection.
configobjectOptionalPipedrive settings. Outbound connectors have none.
record_typestringOptionalInbound. The records whose changes start runs: deal, lead, person, organization, activity, or note. Dashboard: Records.Default: deal
actionstringOptionalInbound. create, change, delete, or any for all three. Dashboard: Event.Default: create
ignore_api_changesbooleanOptionalInbound. 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.

ValueModesDescription
WebhookInboundThe connector's webhook in Pipedrive. connic registers it when you save the connector, so you don't create it in Pipedrive.
Webhook passwordInboundThe 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:

payload.json
{
  "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": { ... }
}
  • event joins record_type and action, which is create, change, or delete.
  • record_id is the record's ID in Pipedrive, a UUID for leads, and title the deal or lead title, the person's or organization's name, or the activity's subject.
  • url links to deals, leads, people, and organizations in Pipedrive, and is empty for deleted records.
  • user_id is the Pipedrive user who made the change, and change_source is app or api.
  • conversation_id stays the same for every event of one record. To give the agent the earlier events as history, set session.key: input.conversation_id in its YAML; the connector doesn't turn on sessions by itself.
  • raw is Pipedrive's full webhook payload as sent: data holds the record, previous the old values of changed fields or, for deletions, the deleted record, and meta the 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:

  1. When the output or payload sets deal_id, lead_id, person_id, or org_id, the note goes to those records. One note can belong to several of them.
  2. 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.
  3. 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.

output.json
{
  "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.

connector-payload.json
{
  "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

LimitValue
Answer to PipedrivePipedrive waits 10 seconds for an answer. connic answers right away and runs the agents afterwards.
Failed deliveriesPipedrive tries a delivery three more times, after 3, 30, and 150 seconds.
Blocked webhookAfter 10 deliveries that fail on the first try, Pipedrive blocks the webhook for 30 minutes and drops its events in that time.
Removed webhookPipedrive 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 user40 for each Pipedrive user, counting every inbound connector that uses the user's API token.
API requestsPipedrive 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 sizeAbout 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.