​
Setup Guide

​
Creating a Pipedrive App

To get started, you’ll need to create an app in the Developer Hub of a Pipedrive account.

  1. Sign up for a free Pipedrive developer sandbox here.
  2. Click the Profile Icon in the top right and select Developer Hub:

  1. Click Create an app and select Create public app. Public apps are intended to allow your users to connect their Pipedrive accounts to your app.

  2. Name the app and add https://passport.useparagon.com/oauth as the Callback URL. Click Save.

While testing your integration, you can use https://passport.useparagon.com/oauth as your Callback URL. Once you set up a Redirect Page to go live, you will need to change this to the URL of your Redirect Page.

  1. Configure your app to use the least privileged scopes required for it to function.

  2. Copy the following information to set up your Pipedrive app with Paragon.

  • Client ID
  • Client Secret

​
Add your Pipedrive App to Paragon

Complete configuration within the Paragon Dashboard and test authentication for your integration.

  1. Select Pipedrive from the Integrations Catalog.

  2. Under Integrations > Connected Integrations > Pipedrive > Configure, fill out your OAuth client credentials from the end of Step 1:

    • Client ID
    • Client Secret

Click “Save changes” button to save your credentials.

Note: Leaving the Client ID and Client Secret blank will use Paragon development keys for user authentication. This is intended for development use only.

You can now test user authentication with the Connect Portal, build workflows, make Pipedrive requests using the SDK, and call Pipedrive ActionKit actions.

​
Connecting to Pipedrive

Once your users have connected their Pipedrive account, you can use the Paragon SDK to access the Pipedrive API on behalf of connected users.

See the Pipedrive REST API documentation for their full API reference.

Any Pipedrive API endpoints can be accessed with the Paragon SDK as shown in this example.

// You can find your project ID in the Overview tab of any Integration

// Authenticate the user
paragon.authenticate(<ProjectId>, <UserToken>);

// Get all persons
await paragon.request("pipedrive", "/persons", {
  method: "GET",
});
            
// Create a person
await paragon.request("pipedrive", "/persons", {
  method: "POST",
  body: {
    "name": "David Bowie",
    "email": "[email protected]"
  }
});

​
Building Pipedrive Workflows

Once your Pipedrive account is connected, you can add steps to perform the following actions:

  • Create Record
  • Update Record
  • Get Record by ID
  • Get Records
  • Delete Record

When creating or updating records in Pipedrive, you can reference data from previous steps by typing {{ to invoke the variable menu.

​
Using Pipedrive Triggers

To use Pipedrive’s webhook triggers, you’ll need to enable the “Administer account” scope in your Pipedrive application:

  1. Log in to the Pipedrive Developer Portal.

  2. Navigate to Tools > Marketplace manager and select your application.

  3. Under OAuth & Access scopes, enable Administer account.

​
Publishing your Pipedrive app

Required: Setting up a Redirect Page is a requirement for allowing customers outside of your Pipedrive Developer account to connect an integration.

If you do not set up this page, the Pipedrive team will not approve your app for public use.

​
Setting up a Redirect Page in your App

Your Pipedrive integration requires a Redirect Page hosted in your application to support an installation flow that begins in the Pipedrive Marketplace (i.e., a user searches the Pipedrive Marketplace for your published app and clicks Install).

For an example implementation of the Redirect Page using React (based on our Next.js sample app), see here.

The Redirect Page should be implemented as follows:

  • Import the Paragon SDK and authenticate a user.

    • Note: If a user is not yet logged into your app, Pipedrive’s requirements suggest that you redirect to a login form, while preserving the intended URL to redirect to upon successful login. In other words, after logging in, your user should see your Redirect Page.

  • Accept and read query parameters, which will be:

    • code in case of a successful installation

    • error in case of an unsuccessful installation or denied consent

  • If the code query parameter is present,

    • Call paragon.completeInstall to complete the OAuth exchange and save a new connected Pipedrive account.
paragon.completeInstall("pipedrive", {
  authorizationCode: codeQueryParam,
  redirectUrl: "https://your-app.url/pipedrive-redirect"
 }).then(() => {
   // Redirect to your app's integrations page
 });

  • If the error query parameter is present,

    • Show this error in your app and allow your user to retry the process.

​
Updating the Allowed Redirect URL

If you were previously testing with https://passport.useparagon.com/oauth as your Pipedrive Redirect URL, you will need to update this value after implementing a Redirect Page:

  1. Log into your Pipedrive Developer Portal.

  2. Navigate to Tools > Marketplace manager and select your application.

  3. Under OAuth & Access scopes > Callback URL, provide the URL of your Redirect Page.