# Pipedrive

Connect Pipedrive and use its tools through the Authlane control plane.

## Prerequisites

Create a Pipedrive OAuth app and choose a company account containing the deals and people your SaaS
will use. The connected user must have access to those CRM records. Keep the official
[API documentation](https://developers.pipedrive.com/docs/api/v1),
[OAuth guide](https://pipedrive.readme.io/docs/marketplace-oauth-authorization), and
[Marketplace Manager](https://pipedrive.readme.io/docs/marketplace-manager) open while configuring
the app. Pipedrive's official MCP server is currently beta; its
[setup guide](https://support.pipedrive.com/en/article/mcp-chatgpt) and
[tool catalog](https://support.pipedrive.com/en/article/mcp-tools) document the live endpoint and
available actions.

## Self-hosted setup

1. Open the Pipedrive Marketplace Manager and create a private or marketplace OAuth app.
2. Register `https://<your-authlane-host>/api/v1/oauth/pipedrive/callback` as the exact callback URL.
3. Copy the generated Client ID and Client Secret.
4. Enable the scopes listed below for the app and publish or install it for the target company.
5. In Authlane, open **Dashboard → Services → Pipedrive**, enable the service, and save the client
   credentials and scopes.

## Configure authentication

Set the Pipedrive Client ID and Client Secret in **Dashboard → Services → Pipedrive**. Authlane
encrypts the Client Secret and uses it only for OAuth token exchange. The connection's provider
response supplies the company-specific API domain used by the adapter.

## Scopes

- **Full tool set** requests `deals:full` and `contacts:full` for read/write access.
- **Read-only tools** requests `deals:read` and `contacts:read` and removes mutations from the
  capability response.
- `search:read` enables `pipedrive_search`.

Pipedrive does not define separate `:write` scopes for these APIs. The `:full` scopes are the
official read/write permissions selected in Marketplace Manager.

## Execution path

Authlane first uses Pipedrive's official beta MCP server at `https://mcp.pipedrive.ai/mcp`. The
server inherits the connected user's Pipedrive permissions and exposes native deal and person
tools. Authlane maps only schema-compatible calls. If an Authlane tool uses filtering or pagination
that the MCP tool cannot represent, it falls back to the connection's company-specific API domain
before any MCP tool call starts. A possibly-started mutation is never retried through the REST API.

Install `@authlane/integration-pipedrive` in the SaaS runtime. The runtime obtains a fresh credential
lease, then talks directly to Pipedrive MCP or its REST API; Authlane never proxies CRM inputs or
results.

## Available tools

### Deals

- `pipedrive_list_deals`
- `pipedrive_get_deal`
- `pipedrive_create_deal`
- `pipedrive_update_deal`
- `pipedrive_search_deals`

### Contacts

- `pipedrive_list_contacts`
- `pipedrive_get_contact`
- `pipedrive_add_contact`
- `pipedrive_update_contact`
- `pipedrive_search_persons`

### Organizations

- `pipedrive_get_organizations`
- `pipedrive_get_organization`
- `pipedrive_add_organization`
- `pipedrive_update_organization`
- `pipedrive_search_organization`

### Activities

- `pipedrive_get_activities`
- `pipedrive_get_activity`
- `pipedrive_add_activity`
- `pipedrive_update_activity`

### Leads and stages

- `pipedrive_search_leads`
- `pipedrive_convert_lead_to_deal`
- `pipedrive_get_lead_conversion_status`
- `pipedrive_get_stages`
- `pipedrive_get_stage`

### Notes

- `pipedrive_get_notes`
- `pipedrive_get_note`
- `pipedrive_add_note`
- `pipedrive_update_note`

### Search

- `pipedrive_search`

## Connection lifecycle

After consent, Authlane encrypts the Pipedrive credential and reports `connected`. When the token
response includes expiry and refresh material, Authlane schedules refresh before expiry. Reconnect
an `expired` or `error` connection that cannot refresh. Disconnect through a new hosted session
after recent reauthentication.

## Troubleshooting

- Do not hard-code one Pipedrive company host; use the API domain bound to the connection.
- Pipedrive MCP is a beta service. If a compatible native MCP tool is unavailable, Authlane safely
  uses the direct API only before a provider tool call begins.
- Deal and person tools require record IDs from the connected company account.
- Verify both the relevant read or write scope and the connected user's visibility when a record is
  missing.