---
title: "Pipedrive"
description: "Connect Pipedrive, obtain the required access and configure permitted actions."
url: "https://documentation.verbatik.com/integrations/pipedrive/"
---

# Pipedrive

Connect Pipedrive, obtain the required access and configure permitted actions.

The API adapter is implemented. Validate your own account and authorized actions before routing production calls.

## Before you start

Connect the account belonging to this business and workspace. Vendor subscriptions, API limits and role permissions still apply.

**API:** Pipedrive API v2 for records/activities; documented v1 endpoints for notes and account metadata

**Authentication:** Personal API token for a customer-controlled account; OAuth for distributable apps

## Get access and connect

1. Sign in to the Pipedrive company account. Open Personal preferences → API to obtain an API token if the user's permissions allow it. Use a dedicated permitted integration user rather than a broad administrator account.
2. In Verbatik set instanceUrl to the company's exact https://your-company.pipedrive.com origin, choose authMode api-token and enter the API token in accessToken. It is sent using Pipedrive's x-api-token header, not embedded in the URL.
3. For a shared OAuth app, create an application in Pipedrive Developer Hub at https://developers.pipedrive.com/ and configure its callback URL and required scopes. Complete the customer's authorization grant.
4. For OAuth mode, enter clientId, clientSecret and refreshToken alongside the access token, and choose authMode oauth. Verbatik renews at https://oauth.pipedrive.com/oauth/token and persists rotated refresh credentials.
5. Run Test connection (users/me), then list pipelines and stages. Use real pipeline/stage IDs for deal creation and stage updates.
6. Configure post-call actions to create or update a deal, append a note and log a completed call activity. People on API v2 activities are linked using participants, matching the current API contract.

## Account requirements

- API access and visibility follow the token owner's Pipedrive permission set and record visibility. OAuth scopes must include each selected action's resource access.
- API tokens are user-bound and may be disabled by account policy. OAuth is required for Pipedrive Marketplace distribution; a platform-wide OAuth client is not created automatically by pasting an access token.
- Existing pipelines, stages, custom fields and organization settings must be used. Required deal fields and record visibility can reject writes.
- Call logging creates a CRM call activity, not carrier dialing or an uploaded audio recording. Phone calls remain under Verbatik's separate telephony setup.

## Permissions

- `base (account metadata)`
- `contacts:read / contacts:full`
- `deals:read / deals:full`
- `activities:read / activities:full`

Grant the subset needed for the actions you enable. API scopes do not override the connected user’s record permissions or vendor validation rules.

## Connection fields

- `accessToken` — Pipedrive API token or OAuth token (optional). Secret fields are saved as workspace credentials.
- `clientId` — OAuth client ID (automatic renewal) (optional). Secret fields are saved as workspace credentials.
- `clientSecret` — OAuth client secret (automatic renewal) (optional). Secret fields are saved as workspace credentials.
- `refreshToken` — OAuth refresh token (automatic renewal) (optional). Secret fields are saved as workspace credentials.
- `instanceUrl` — Pipedrive company origin (required).
- `authMode` — Authentication mode: api-token or oauth (optional).

## Available actions

- `test_connection` — **Read** · available for after-call automation. Read account or schema metadata to verify credentials without creating records.
- `find_contact` — **Read** · available for after-call automation. Search Pipedrive people by name, email or phone.
- `create_contact` — **Write** · available for after-call automation. Create a person, optionally attached to an existing organization.
- `get_persons` — **Read** · available for after-call automation. Read a known Pipedrive persons record.
- `update_persons` — **Write** · available for after-call automation. Update documented API v2 fields, including deal pipeline_id and stage_id.
- `get_organizations` — **Read** · available for after-call automation. Read a known Pipedrive organizations record.
- `update_organizations` — **Write** · available for after-call automation. Update documented API v2 fields, including deal pipeline_id and stage_id.
- `get_deals` — **Read** · available for after-call automation. Read a known Pipedrive deals record.
- `update_deals` — **Write** · available for after-call automation. Update documented API v2 fields, including deal pipeline_id and stage_id.
- `create_organization` — **Write** · available for after-call automation. Create a Pipedrive organization.
- `create_deal` — **Write** · available for after-call automation. Create a deal with known person, organization, pipeline and stage IDs where applicable.
- `list_pipelines` — **Read** · available for after-call automation. Read Pipedrive deal pipelines.
- `list_stages` — **Read** · available for after-call automation. Read stages for an existing pipeline.
- `create_task` — **Write** · available for after-call automation. Create an unfinished Pipedrive task activity.
- `log_call` — **Write** · available for after-call automation. Record a completed call activity against a person or deal. Does not place a phone call.
- `add_note` — **Write** · available for after-call automation. Attach a note to a person, organization or deal.


## Verify before going live

Run Test connection and one read action against a known permitted record. Then test each intended write in an authorized sandbox. Check the provider’s own record and the Verbatik receipt. Publish the agent after assigning its tools. If a write has an unknown outcome, reconcile it with the vendor before trying again.

## Vendor documentation

- [Setup and API documentation](https://pipedrive.readme.io/docs/core-api-concepts-authentication)
- [Additional provider reference](https://pipedrive.readme.io/docs/marketplace-oauth-authorization)
- [Additional provider reference](https://pipedrive.readme.io/docs/marketplace-oauth-scopes)
- [Additional provider reference](https://developers.pipedrive.com/docs/api/v1/Persons)
- [Additional provider reference](https://developers.pipedrive.com/docs/api/v1/Activities)
- [Additional provider reference](https://developers.pipedrive.com/docs/api/v1/Notes)