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

# Pipedrive

> Add a bot to Pipedrive using the official integration.

{/* vale on */}

[Open in Hub](https://studio.botpress.cloud/home?exploreHub=1\&hubItemId=intver_01K6BG0EMJ1FQ0E5DCZZEN9301)
*v5.0.1*

The official Pipedrive integration allows your bot to create, update and search for Pipedrive contacts.

## Setup

> [!NOTE]
>
> You will need:
>
> * A [published bot](https://botpress.com/docs/get-started/quick-start.md)
> * A [Pipedrive account](https://www.pipedrive.com/en/register)

**1. Install the integration in Botpress**

First, install the integration to your bot:

1. In Botpress Studio, select **Explore Hub** in the upper-right corner.
2. Search for the **Pipedrive** integration, then select **Install Integration**.

In the **Configuration** menu, you should see one field: **API Key**. Leave it empty for now—you'll come back to it after creating your Pipedrive API key.

**2. Create a Pipedrive API key**

Next, create a Pipedrive API key:

1. [Log in to Pipedrive](https://app.pipedrive.com/auth/login).

   > [!WARNING]
   >
   > The API key will inherit the permissions of whatever user you're logging in as. Because of this, we recommend using a dedicated Pipedrive user account for the API key.
   >
   > This makes it easier to maintain the right permissions for the integration, or to rotate the key if it becomes compromised.

2. Open the **My Account** menu in the upper-right corner, then select **Personal preferences**.

3. Navigate to the **API** tab. You should see your personal API key—copy it.

> [!TIP]
>
> If you don't have an API key, select **Generate new token**.

**3. Configure the integration in Botpress**

Now, you can finish setting up the integration in Botpress:

1. In the integration's **API Key** field, paste your Pipedrive API key.
2. Select **Save Configuration**.

> [!TIP]
>
> Your Pipedrive integration is ready. You can use the integration's [Cards](#cards) to interact with your Pipedrive contacts.

***

## Cards

{/* vale off */}

Here's a reference for all [Cards](https://botpress.com/docs/studio/concepts/cards/introduction.md) available with the integration:

### Add Person

Add a person in Pipedrive

**input** `object`

**name** `string` *required*

The name of the person

**owner\_id** `number`

The ID of the owner of the person

**org\_id** `number`

The ID of the organization the person belongs to

**emailValue** `string`

Email address

**emailPrimary** `boolean`

Mark the email as primary

**phoneValue** `string`

Phone number

**phonePrimary** `boolean`

Mark the phone as primary

**visible\_to** `number`

The visibility of the person

**output** `object`

**success** `boolean`

**data** `object`

**id** `number`

**name** `string`

**first\_name** `string`

**last\_name** `string`

**owner\_id** `number`

**org\_id** `number | null`

**add\_time** `string | null`

**update\_time** `string | null`

**emails** `array`

**array item properties**

**value** `string`

**primary** `boolean`

**label** `string`

**phones** `array`

**array item properties**

**value** `string`

**primary** `boolean`

**label** `string`

**is\_deleted** `boolean`

**visible\_to** `number`

**label\_ids** `array`

**picture\_id** `number | null`

**postal\_address** `object`

**street\_number** `string`

**route** `string`

**sublocality** `string`

**locality** `string`

**admin\_area\_level\_1** `string`

**admin\_area\_level\_2** `string`

**country** `string`

**postal\_code** `string`

**formatted\_address** `string`

**notes** `string`

**im** `array`

**array item properties**

**protocol** `string`

**value** `string`

**birthday** `string`

**job\_title** `string`

### Find Person

Search for a person in Pipedrive

**input** `object`

**term** `string` *required*

The search term to look for (minimum 2 characters)

**fields** `enum\<string\>`

Which fields to search in (custom\_fields, email, notes, phone, name)

Available options: `custom_fields`, `email`, `notes`, `phone`, `name`

**organization\_id** `number`

The ID of the organization to search in

**exact\_match** `boolean`

Whether to search for exact matches only

**output** `object`

**success** `boolean`

**data** `object`

**items** `array`

**array item properties**

**result\_score** `number`

**item** `object`

**id** `number`

**type** `string`

**name** `string`

**phones** `array`

**emails** `array`

**visible\_to** `number`

**owner** `object`

**id** `number`

**name** `string`

**email** `string`

**organization** `object`

**id** `number`

**name** `string`

**custom\_fields** `array`

**notes** `array`

**additional\_data** `string`

### Update Person

Update a person in Pipedrive

**input** `object`

**person\_id** `number` *required*

The ID of the person to update

**name** `string`

The name of the person

**owner\_id** `number`

The ID of the owner of the person

**org\_id** `number`

The ID of the organization the person belongs to

**emailValue** `string`

Email address

**emailPrimary** `boolean`

Mark the email as primary

**phoneValue** `string`

Phone number

**phonePrimary** `boolean`

Mark the phone as primary

**visible\_to** `number`

The visibility of the person

**output** `object`

**success** `boolean`

**data** `object`

**id** `number`

**name** `string`

**first\_name** `string`

**last\_name** `string`

**owner\_id** `number`

**org\_id** `number | null`

**add\_time** `string | null`

**update\_time** `string | null`

**emails** `array`

**array item properties**

**value** `string`

**primary** `boolean`

**label** `string`

**phones** `array`

**array item properties**

**value** `string`

**primary** `boolean`

**label** `string`

**is\_deleted** `boolean`

**visible\_to** `number`

**label\_ids** `array`

**picture\_id** `number | null`

**postal\_address** `object`

**street\_number** `string`

**route** `string`

**sublocality** `string`

**locality** `string`

**admin\_area\_level\_1** `string`

**admin\_area\_level\_2** `string`

**country** `string`

**postal\_code** `string`

**formatted\_address** `string`

**notes** `string`

**im** `array`

**array item properties**

**protocol** `string`

**value** `string`

**birthday** `string`

**job\_title** `string`

***

## Troubleshooting

If you run into errors when using the integration's Cards, check out your bot's [Logs](https://botpress.com/docs/studio/concepts/debugger-logs-json.md#logs) and locate the error message:

> [accordion] (Field) must be (data type)
>
> Usually this means:
>
> * Not all the Card's required input fields were filled
> * One of the fields contained invalid data
>
> Double-check the input fields and try again. If you're letting your bot fill the input fields automatically based on context, make sure it's providing input that conforms to the Card's expected format.

> [accordion] An unexpected error occurred
>
> This could mean a few things:
>
> * Your Pipedrive API key may have been revoked. [Create a new one](#setup) and update your bot's configuration.
> * Your API key may belong to a user that [doesn't have permission to perform the Card's action](https://support.pipedrive.com/en/article/permission-sets). We recommend creating a dedicated Pipedrive user account for the API key and ensuring it has the necessary permissions for the Cards you want to use.
> * You may have exceeded Pipedrive's API rate limit. Wait and retry according to [Pipedrive's documentation](https://pipedrive.readme.io/docs/core-api-concepts-rate-limiting).

> [!TIP]
>
> You can also consult Pipedrive's [error code reference](https://pipedrive.readme.io/docs/error-codes-and-troubleshooting-for-messaging-app-extension#expected-error-codes-for-the-messaging-extensions-endpoints) for further troubleshooting.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.