💡 This article is for you if…

1. You want a quick start alternative to reading through the vast amount of Pipedrive documentation.
2. You’ve built your Pipedrive integration already but want to learn about common gotchas and best practices to make your integration more robust.
3. You’ve built an internal Pipedrive integration before but not one that’s customer-facing.

Pipedrive is a powerful sales CRM software that helps businesses manage leads, deals, and communications. It is designed to be easy to use, but building a customer-facing integration with Pipedrive can be a daunting task. Fortunately, we’ve already gone through the headache of building a complex native Pipedrive integration and have distilled all of the wisdom and gotchas we’ve picked up over the years into this guide.

If you’re unfamiliar with what native integrations are in the first place, you can reference our previous blog post aptly titled what are native integrations?

As a side note, I’ll be using the Vessel SDK to build this integration so I don’t have to worry about setting up Auth or handling any Pipedrive API quirks.

If you don’t want to use Vessel, no worries, I’ve kept this guide as generic as possible and it will be useful regardless of how you decide to build your native Pipedrive integration.

Getting Setup For your Pipedrive Integration

Before you dive into writing code for your Pipedrive integration, there are a few logistical things you’ll want to get out of the way.

Create a Developer Account

First, you’ll need access to a developer account where we can muck around with fake data without worrying about messing up anything in a real Pipedrive account. To create a developer account, head over to the Pipedrive Developer Portal and sign up for a free account. You'll need this account to access the Pipedrive API and create an OAuth app.

Create A Pipedrive OAuth App

If you’re using Vessel, you can go ahead and skip this step since we’ve got a pre-approved Pipedrive application you can use. If you’re not using Vessel, you’ll need to keep reading to learn how to set up an OAuth app.

Here’s how you can create a Pipedrive OAuth:

1. Log in to your Pipedrive Developer Portal account.
2. Go click on "Create an app” (should be on the page you land on).

1. Select “Create public app” from the dropdown selection.

1. Fill in the App Name and the Callback URL, you can come back and change these later. Fill in localhost for the callback URL for now.
2. Turn on Contacts for the scopes, we can do read-only for now:

1. At the bottom of the “OAuth and access scopes” tab, you'll see the client ID and client secret. Make sure to securely store these credentials, as they will be needed for authentication.

The Pipedrive API at a Glance

Here’s a quick summary of some important things to know about the Pipedrive API.

Authentication

The first step to making an API call is to ask your user for permission to access their data. We do this by “installing” the OAuth app we created in the step above (or already had if you’re using Vessel) inside of their CRM instance.

During this process, your user will be shown a popup window that asks them to grant you permission to read and write their data.

Which objects they grant you access to will depend on which scopes you selected when creating the OAuth app. In our case, the user would only see permissions related to contacts (such as ”View properties and other details about contacts.”) since that’s all we requested when creating our OAuth app.

OAuth is a complicated and nuanced topic, for brevity, I’m not going to touch on how to build out an OAuth flow since it’s not Pipedrive-specific.

If you’re new to OAuth and just need to get something going fast or don’t want to deal with the notorious headache of OAuth, you can use a framework like Vessel to handle it for you.

If you’d prefer to do this yourself, you can read Pipedrive tutorial on OAuth which is actually pretty decent. Forewarning, the Pipedrive tutorial is very Pipedrive specific so if you know you’ll need to build other integrations in the future, I’d invest in doing more research so you understand how to build a more generic Auth flow since OAuth is an infamously difficult problem.

Regardless of how you choose to build authentication, the important part is that you’re able to get an accessToken for your user. The accessToken is what will allow us to pull and push data to the user's Pipedrive instance.

Making an API Call

Now that you’re able to authenticate your user, you can begin making API calls to their Pipedrive account 🥳! In this section, we’ll explore how to read and write to the Pipedrive API in real-time.

Reading From the API

Reading from the Pipedrive API is relatively straightforward, with various endpoints available for fetching data on deals, organizations, persons, and more. However, there are a few gotchas to be aware of:

1. Pagination: Pipedrive's API uses pagination, with a default limit of 100 items per page which is on the smaller side. When making API requests, you'll want to specify the start and limit parameters to change how much data is fetched.
2. SDK: We’ve run into quite a few issues with the Pipedrive SDK and suggest just making a raw request.

Through Pipedrive API

With Vessel

Writing to the API

Writing to the Pipedrive API is also quite simple, with endpoints available for creating and updating various objects such as deals, organizations, and persons. However, there are a few gotchas to watch out for:

1. Validation: Pipedrive's API performs validation on the data you send, and will return an error if the data doesn't meet the required format or constraints.
2. Rate limits: Pipedrive enforces rate limits on API requests, with some pretty big variability depending on what plan your customer is on. Be sure to handle rate limit errors and implement backoff logic when necessary.

Through Pipedrive API

With Vessel

Closing Thoughts

Publishing your Application

Once you've completed the development of your Pipedrive integration, you might consider publishing it to the Pipedrive App Marketplace. Publishing your integration will allow other Pipedrive users to discover and install your integration, increasing its reach and potential user base.

To publish your application, you'll need to go through the application review and approval process. This process ensures that your integration meets the necessary quality and security standards set by Pipedrive. You can find more information on the Pipedrive Developer Portal.

About Us

Hopefully, you found this article helpful for building out your native Pipedrive integration. I know I certainly wish something like this existed when we built out our Pipedrive integration.

If you decided to give Vessel a spin while following this tutorial, thank you. If you have any feedback while using the SDK, don’t hesitate to reach out at support@vessel.devWe’re a team of engineers at heart and take every piece of feedback extremely seriously.

if you’re curious to learn more about why we started Vessel and how we view the future of customer-facing integrations, you can read more in our “what are native integration platforms” posts.

On that note, if you ever have any questions about building a Pipedrive integration while you’re going through this tutorial, regardless of if you decide to use Vessel, don’t hesitate to reach out at zach@vessel.dev and I’ll be more than happy to personally help.