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

# Connect Pipedrive to Stairoids for Real-Time Deal Signals

> Sync Pipedrive deal stage changes, activity completions, and won/lost events as signals, and push updates back to deals and persons automatically.

The Pipedrive integration connects your deal pipeline directly to Stairoids' signal engine. Deal movements, completed activities, and won/lost outcomes become actionable signals that can trigger cross-tool automations the moment they happen. Outgoing actions write notes, create activities, and update deal and person fields in Pipedrive — so your pipeline stays current without any manual data entry.

## Prerequisites

Before connecting, make sure you have:

* A Pipedrive account on a plan that supports webhooks (Advanced plan or higher)
* **Admin** role in Pipedrive (required to generate an API key)
* Admin access in your Stairoids workspace

<Tip>
  Stairoids uses Pipedrive's native webhook system to receive deal and activity events in real time. Make sure your Pipedrive plan includes webhook support before attempting to connect. On the Essential plan, webhooks are not available and signals will not flow.
</Tip>

## Connect Pipedrive

<Steps>
  <Step title="Generate your Pipedrive API key">
    In Pipedrive, click your avatar in the top-right corner and go to **Personal Preferences → API**. Copy your personal API token.
  </Step>

  <Step title="Open Integration Settings in Stairoids">
    Navigate to **Settings → Integrations** and click **Add Integration**.
  </Step>

  <Step title="Select Pipedrive">
    Choose **Pipedrive** from the integration catalog. Paste your API token into the **API Key** field and click **Connect**.
  </Step>

  <Step title="Choose events to sync">
    Toggle on the incoming signal event types you want Stairoids to track. You can adjust these selections later from **Settings → Integrations → Pipedrive → Configure**.
  </Step>

  <Step title="Verify the connection">
    Stairoids registers a webhook in your Pipedrive account and confirms the connection. Go to your **Signal Feed** — Pipedrive signals should start arriving within moments of the next deal or activity update in your pipeline.
  </Step>
</Steps>

## Supported incoming signal events

| Event              | Signal type          | Key properties                                                   |
| ------------------ | -------------------- | ---------------------------------------------------------------- |
| Deal created       | `deal_created`       | `deal_id`, `deal_title`, `owner_id`, `pipeline_id`, `stage_id`   |
| Deal stage changed | `deal_stage_changed` | `deal_id`, `deal_title`, `from_stage`, `to_stage`, `pipeline_id` |
| Deal won           | `deal_won`           | `deal_id`, `deal_title`, `value`, `currency`, `won_at`           |
| Deal lost          | `deal_lost`          | `deal_id`, `deal_title`, `lost_reason`, `lost_at`                |
| Activity completed | `activity_completed` | `activity_id`, `type`, `deal_id`, `person_id`, `done_at`         |
| Note added         | `note_added`         | `note_id`, `deal_id`, `person_id`, `content_preview`             |

## Supported outgoing actions

When a Stairoids automation targets Pipedrive, it can perform the following actions:

* **Update deal stage** — move a deal to a new stage within any pipeline
* **Add note** — create a note on a deal or person record
* **Create activity** — schedule a call, email, meeting, or task against a deal or person
* **Update person fields** — write values to standard or custom person fields

## Field mapping

Stairoids maps Pipedrive's standard deal and person fields to its internal schema automatically. The deal's associated person email maps to `contact.email`, and the organization name maps to `account.name`. Custom Pipedrive fields are preserved under `signal.properties` using their field key.

To map custom Pipedrive fields to Stairoids account or contact fields, go to **Settings → Integrations → Pipedrive → Field Mapping** and configure the mappings manually.

## Troubleshooting

<Accordion title="Deal updates not syncing to Stairoids">
  1. Navigate to **Settings → Integrations → Pipedrive** and confirm the connection status is **Active**.
  2. Open Pipedrive and go to **Company Settings → Webhooks** (under the Tools & Integrations section). Confirm a webhook registered by Stairoids is present and shows a green status. If it's missing, reconnect the integration — Stairoids will re-register it.
  3. Check that the event type for the update you're expecting (e.g., `deal_stage_changed`) is toggled on in Stairoids' Pipedrive configuration.
  4. If the webhook exists but events aren't arriving, Pipedrive may have paused it after repeated delivery failures. Re-enable the webhook in Pipedrive, then trigger another deal update to test.
</Accordion>

<Accordion title="API key rejected during setup">
  1. Confirm you're using your **personal API token** from Pipedrive (under Personal Preferences → API), not a company-level or OAuth token.
  2. Make sure the Pipedrive user whose token you're using has **Admin** role. Tokens from non-admin users will be rejected because Stairoids requires permission to register webhooks, which is an admin-only action in Pipedrive.
  3. If your organization uses Pipedrive's IP allowlist, add Stairoids' outbound IP ranges. Contact [support@stairoids.com](mailto:support@stairoids.com) for the current IP list.
</Accordion>

<Accordion title="Outgoing actions not updating Pipedrive records">
  1. Confirm the Pipedrive API token stored in Stairoids is still valid. Tokens can be regenerated in Pipedrive, which invalidates the old one. If you've recently regenerated your Pipedrive API token, reconnect the integration with the new token.
  2. Check the automation's action configuration — ensure the deal ID or person ID field is correctly mapped from the incoming signal. If the ID field is empty, the outgoing action has no record to update and will silently skip.
  3. Review the **Automation Logs** in Stairoids (**Automations → \[your automation] → Logs**) for any error messages from the Pipedrive API.
</Accordion>