Pipedrive client for NodeJS based apps

Pipedrive is a sales pipeline software that gets you organized. It's a powerful sales CRM with effortless sales pipeline management. See www.pipedrive.com for details.

This is the official Pipedrive API wrapper-client for NodeJS based apps, distributed by Pipedrive Inc freely under the MIT licence. It provides convenient access to the Pipedrive API, allowing you to operate with objects such as Deals, Persons, Organizations, Products and much more.

Installation

npm install pipedrive

⚠️ Version 10 is a complete rewrite of the library and introduces breaking changes in the client API. This release includes improved OAuth 2 support, async & await / promises and access to all Pipedrive API endpoints.

If you have been using a previous version of the client and cannot upgrade immediately, older versions are still available.

Please use the issues page for reporting bugs or leaving feedback. Note that most of the code is automatically generated.

API Reference

The Pipedrive RESTful API Reference can be found at https://developers.pipedrive.com/docs/api/v1

License

This Pipedrive API client is distributed under the MIT license.

How to use

With a pre-set API token

const express = require('express');
const app = express();
const lib = require('pipedrive');
 
const PORT = 1800;
 
lib.Configuration.apiToken = 'YOUR_API_TOKEN_HERE';
 
app.listen(PORT, () => {
    console.log(`Listening on port ${PORT}`);
});
 
app.get('/', async (req, res) => {
    const user = await lib.UsersController.getCurrentUserData();
 
    res.send(user);
});
 

With OAuth 2

In order to setup authentication in the API client, you need the following information.

API client can be initialized as following:

const lib = require('pipedrive');
 
// Configuration parameters and credentials
lib.Configuration.oAuthClientId = "oAuthClientId"; // OAuth 2 Client ID
lib.Configuration.oAuthClientSecret = "oAuthClientSecret"; // OAuth 2 Client Secret
lib.Configuration.oAuthRedirectUri = "oAuthRedirectUri"; // OAuth 2 Redirection endpoint or Callback Uri
 

You must now authorize the client.

Authorizing your client

Your application must obtain user authorization before it can execute an endpoint call. The SDK uses OAuth 2.0 authorization to obtain a user's consent to perform an API request on user's behalf.

1. Obtaining user consent

To obtain user's consent, you must redirect the user to the authorization page. The buildAuthorizationUrl() method creates the URL to the authorization page.

const oAuthManager = lib.OAuthManager;
const authUrl = oAuthManager.buildAuthorizationUrl();
// open up the authUrl in the browser

2. Handle the OAuth server response

Once the user responds to the consent request, the OAuth 2.0 server responds to your application's access request by using the URL specified in the request.

If the user approves the request, the authorization code will be sent as the code query string:

https://example.com/oauth/callback?code=XXXXXXXXXXXXXXXXXXXXXXXXX

If the user does not approve the request, the response contains an error query string:

https://example.com/oauth/callback?error=access_denied

3. Authorize the client using the code

After the server receives the code, it can exchange this for an access token. The access token is an object containing information for authorizing the client and refreshing the token itself.

const tokenPromise = oAuthManager.authorize(code);

The Node.js SDK supports both callbacks and promises. So, the authorize call returns a promise and also returns response back in the callback (if one is provided)

Refreshing token

Access tokens may expire after sometime. To extend its lifetime, you must refresh the token.

const refreshPromise = oAuthManager.refreshToken();
refreshPromise.then(() => {
    // token has been refreshed
} , (exception) => {
    // error occurred, exception will be of type lib/Exceptions/OAuthProviderException
});

If a token expires, the SDK will attempt to automatically refresh the token before the next endpoint call which requires authentication.

Storing an access token for reuse

It is recommended that you store the access token for reuse.

This code snippet stores the access token in a session for an express application. It uses the cookie-parser and cookie-session npm packages for storing the access token.

const express = require('express');
const cookieParser = require('cookie-parser');
const cookieSession = require('cookie-session');
 
const app = express();
app.use(cookieParser());
app.use(cookieSession({
  name: 'session',
  keys: ['key1']
}));
 
const lib = require('pipedrive');
...
// store token in the session
req.session.token = lib.Configuration.oAuthToken;

However, since the the SDK will attempt to automatically refresh the token when it expires, it is recommended that you register a token update callback to detect any change to the access token.

lib.Configuration.oAuthTokenUpdateCallback = function(token) {
    // getting the updated token
    req.session.token = token;
}

The token update callback will be fired upon authorization as well as token refresh.

Creating a client from a stored token

To authorize a client from a stored access token, just set the access token in Configuration along with the other configuration parameters before making endpoint calls:

NB! This code only supports one client and should not be used as production code. Please store a separate access token for each client.

const express = require('express');
const cookieParser = require('cookie-parser');
const cookieSession = require('cookie-session');
 
const app = express();
app.use(cookieParser());
app.use(cookieSession({
  name: 'session',
  keys: ['key1']
}));
 
const lib = require('pipedrive');
 
app.get('/', (req, res) => {
    lib.Configuration.oAuthToken = req.session.token; // the access token stored in the session
});

Complete example

This example demonstrates an express application (which uses cookie-parser and cookie-session) for handling session persistence.

In this example, there are 2 endpoints. The base endpoint '/' first checks if the token is stored in the session. If it is, API endpoints can be called using the corresponding SDK controllers.

However, if the token is not set in the session, then authorization URL is built and opened up. The response comes back at the '/callback' endpoint, which uses the code to authorize the client and store the token in the session. It then redirects back to the base endpoint for calling endpoints from the SDK.

const express = require('express');
const app = express();
const cookieParser = require('cookie-parser');
const cookieSession = require('cookie-session');
 
app.use(cookieParser());
app.use(cookieSession({
  name: 'session',
  keys: ['key1']
}));
const PORT = 1800;
 
const lib = require('pipedrive');
const oAuthManager = lib.OAuthManager;
 
lib.Configuration.oAuthClientId = 'oAuthClientId'; // OAuth 2 Client ID
lib.Configuration.oAuthClientSecret = 'oAuthClientSecret'; // OAuth 2 Client Secret
lib.Configuration.oAuthRedirectUri = 'http://localhost:1800/callback'; // OAuth 2 Redirection endpoint or Callback Uri
 
 
app.listen(PORT, () => {
    console.log(`Listening on port ${PORT}`);
});
 
app.get('/', async (req, res) => {
    if (req.session.token !== null && req.session.token !== undefined) {
        // token is already set in the session
        // now make API calls as required
        // client will automatically refresh the token when it expires and call the token update callback
        const user = await lib.UsersController.getCurrentUserData();
 
        res.send(user);
    } else {
        const authUrl = oAuthManager.buildAuthorizationUrl();
 
        res.redirect(authUrl);
    }
});
 
app.get('/callback', (req, res) => {
    const authCode = req.query.code;
    const promise = oAuthManager.authorize(authCode);
 
    promise.then(() => {
        req.session.token = lib.Configuration.oAuthToken;
        res.redirect('/');
    }, (exception) => {
        // error occurred, exception will be of type lib/Exceptions/OAuthProviderException
    });
});
 

Contributing

Please be aware that most of the code is auto-generated. You are welcome to suggest changes and report bugs. However, any updates will have to be implemented in the underlying generator.

How to Test

These tests use Mocha framework for testing, coupled with Chai for assertions. These dependencies need to be installed for tests to run. Tests can be run in a number of ways:

Method 1 (Run all tests)

1. Navigate to the root directory of the SDK folder from command prompt.
2. Type mocha --recursive to run all the tests.

Method 2 (Run all tests)

1. Navigate to the ../test/Controllers/ directory from command prompt.
2. Type mocha * to run all the tests.

Method 3 (Run specific controller's tests)

1. Navigate to the ../test/Controllers/ directory from command prompt.
2. Type mocha Pipedrive API v1Controller to run all the tests in that controller file.

To increase mocha's default timeout, you can change the TEST_TIMEOUT parameter's value in TestBootstrap.js.

Class Reference

List of Controllers

• ActivitiesController
• ActivityFieldsController
• ActivityTypesController
• CurrenciesController
• DealFieldsController
• DealsController
• FilesController
• FiltersController
• GlobalMessagesController
• GoalsController
• MailMessagesController
• MailThreadsController
• NoteFieldsController
• NotesController
• OrganizationFieldsController
• OrganizationRelationshipsController
• OrganizationsController
• PermissionSetsController
• PersonFieldsController
• PersonsController
• PipelinesController
• ProductFieldsController
• ProductsController
• RecentsController
• RolesController
• SearchResultsController
• StagesController
• TeamsController
• UserConnectionsController
• UserSettingsController
• UsersController
• WebhooksController

ActivitiesController

Get singleton instance

The singleton instance of the ActivitiesController class can be accessed from the API Client.

var controller = lib.ActivitiesController;

deleteMultipleActivitiesInBulk

Marks multiple activities as deleted.

function deleteMultipleActivitiesInBulk(ids, callback)

Parameters

Example Usage

 
    var ids = 'ids';
 
    controller.deleteMultipleActivitiesInBulk(ids, function(error, response, context) {
 
    
    });

getAllActivitiesAssignedToAParticularUser

Returns all activities assigned to a particular user.

function getAllActivitiesAssignedToAParticularUser(input, callback)

Parameters

Example Usage

 
    var input = [];
        input['userId'] = 58;
        input['filterId'] = 58;
        input['type'] = 'type';
        input['start'] = 0;
        input['limit'] = 58;
        input['startDate'] = '2019-11-22';
        input['endDate'] = '2019-11-22';
        input['done'] = Object.keys(NumberBoolean)[0];
 
    controller.getAllActivitiesAssignedToAParticularUser(input, function(error, response, context) {
 
    
    });

addAnActivity

Adds a new activity. Includes more_activities_scheduled_in_context property in response's additional_data which indicates whether there are more undone activities scheduled with the same deal, person or organization (depending on the supplied data). For more information on how to add an activity, see this tutorial.

function addAnActivity(input, callback)

Parameters

Example Usage

 
    var input = [];
        input['subject'] = 'subject';
        input['type'] = 'type';
        input['done'] = Object.keys(NumberBoolean)[0];
        input['dueDate'] = '2019-11-22';
        input['dueTime'] = due_time;
        input['duration'] = 'duration';
        input['userId'] = 58;
        input['dealId'] = 58;
        input['personId'] = 58;
        input['participants'] = 'participants';
        input['orgId'] = 58;
        input['note'] = 'note';
 
    controller.addAnActivity(input, function(error, response, context) {
 
    
    });

deleteAnActivity

Deletes an activity.

function deleteAnActivity(id, callback)

Parameters

Example Usage

 
    var id = 58;
 
    controller.deleteAnActivity(id, function(error, response, context) {
 
    
    });

getDetailsOfAnActivity

Returns details of a specific activity.

function getDetailsOfAnActivity(id, callback)

Parameters

Example Usage

 
    var id = 58;
 
    controller.getDetailsOfAnActivity(id, function(error, response, context) {
 
    
    });

updateEditAnActivity

Modifies an activity. Includes more_activities_scheduled_in_context property in response's additional_data which indicates whether there are more undone activities scheduled with the same deal, person or organization (depending on the supplied data).

function updateEditAnActivity(input, callback)

Parameters

Example Usage

 
    var input = [];
        input['id'] = 58;
        input['subject'] = 'subject';
        input['type'] = 'type';
        input['done'] = Object.keys(NumberBoolean)[0];
        input['dueDate'] = '2019-11-22';
        input['dueTime'] = due_time;
        input['duration'] = 'duration';
        input['userId'] = 58;
        input['dealId'] = 58;
        input['personId'] = 58;
        input['participants'] = 'participants';
        input['orgId'] = 58;
        input['note'] = 'note';
 
    controller.updateEditAnActivity(input, function(error, response, context) {
 
    
    });

Back to List of Controllers

ActivityFieldsController

Get singleton instance

The singleton instance of the ActivityFieldsController class can be accessed from the API Client.

var controller = lib.ActivityFieldsController;

getAllFieldsForAnActivity

Return list of all fields for activity

function getAllFieldsForAnActivity(callback)

Example Usage

 
 
    controller.getAllFieldsForAnActivity(function(error, response, context) {
 
    
    });

Back to List of Controllers

ActivityTypesController

Get singleton instance

The singleton instance of the ActivityTypesController class can be accessed from the API Client.

var controller = lib.ActivityTypesController;

deleteMultipleActivityTypesInBulk

Marks multiple activity types as deleted.

function deleteMultipleActivityTypesInBulk(ids, callback)

Parameters

Example Usage

 
    var ids = 'ids';
 
    controller.deleteMultipleActivityTypesInBulk(ids, function(error, response, context) {
 
    
    });

getAllActivityTypes

Returns all activity types

function getAllActivityTypes(callback)

Example Usage

 
 
    controller.getAllActivityTypes(function(error, response, context) {
 
    
    });

addNewActivityType

Adds a new activity type, returns the ID, the key_string and the order number of the newly added activity type upon success.

function addNewActivityType(input, callback)

Parameters

Example Usage

 
    var input = [];
        input['name'] = 'name';
        input['iconKey'] = Object.keys(IconKey)[0];
        input['color'] = 'color';
 
    controller.addNewActivityType(input, function(error, response, context) {
 
    
    });

deleteAnActivityType

Marks an activity type as deleted.

function deleteAnActivityType(id, callback)

Parameters

Example Usage

 
    var id = 58;
 
    controller.deleteAnActivityType(id, function(error, response, context) {
 
    
    });

updateEditActivityType

Updates an activity type.

function updateEditActivityType(input, callback)

Parameters

Example Usage

 
    var input = [];
        input['id'] = 58;
        input['name'] = 'name';
        input['iconKey'] = Object.keys(IconKey)[0];
        input['color'] = 'color';
        input['orderNr'] = 58;
 
    controller.updateEditActivityType(input, function(error, response, context) {
 
    
    });

Back to List of Controllers

CurrenciesController

Get singleton instance

The singleton instance of the CurrenciesController class can be accessed from the API Client.

var controller = lib.CurrenciesController;

getAllSupportedCurrencies

Returns all supported currencies in given account which should be used when saving monetary values with other objects. The 'code' parameter of the returning objects is the currency code according to ISO 4217 for all non-custom currencies.

function getAllSupportedCurrencies(term, callback)

Parameters

Example Usage

 
    var term = 'term';
 
    controller.getAllSupportedCurrencies(term, function(error, response, context) {
 
    
    });

Back to List of Controllers

DealFieldsController

Get singleton instance

The singleton instance of the DealFieldsController class can be accessed from the API Client.

var controller = lib.DealFieldsController;

deleteMultipleDealFieldsInBulk

Marks multiple fields as deleted.

function deleteMultipleDealFieldsInBulk(ids, callback)

Parameters

Example Usage

 
    var ids = 'ids';
 
    controller.deleteMultipleDealFieldsInBulk(ids, function(error, response, context) {
 
    
    });

getAllDealFields

Returns data about all fields deals can have

function getAllDealFields(input, callback)

Parameters

Example Usage

 
    var input = [];
        input['start'] = 0;
        input['limit'] = 58;
 
    controller.getAllDealFields(input, function(error, response, context) {
 
    
    });

addANewDealField

Adds a new deal field. For more information on adding a new custom field, see this tutorial.

function addANewDealField(input, callback)

Parameters

Example Usage

 
    var input = [];
        input['contentType'] = 'Content-Type';
        input['body'] = {
        id : 21
    };
 
    controller.addANewDealField(input, function(error, response, context) {
 
    
    });

deleteADealField

Marks a field as deleted. For more information on how to delete a custom field, see this tutorial.

function deleteADealField(id, callback)

Parameters

Example Usage

 
    var id = 58;
 
    controller.deleteADealField(id, function(error, response, context) {
 
    
    });

getOneDealField

Returns data about a specific deal field.

function getOneDealField(id, callback)

Parameters

Example Usage

 
    var id = 58;
 
    controller.getOneDealField(id, function(error, response, context) {
 
    
    });

updateADealField

Updates a deal field. See an example of updating custom fields’ values in this tutorial.

function updateADealField(input, callback)

Parameters

Example Usage

 
    var input = [];
        input['id'] = 58;
        input['name'] = 'name';
        input['options'] = 'options';
 
    controller.updateADealField(input, function(error, response, context) {
 
    
    });

Back to List of Controllers

DealsController

Get singleton instance

The singleton instance of the DealsController class can be accessed from the API Client.

var controller = lib.DealsController;

deleteMultipleDealsInBulk

Marks multiple deals as deleted.

function deleteMultipleDealsInBulk(ids, callback)

Parameters

Example Usage

 
    var ids = 'ids';
 
    controller.deleteMultipleDealsInBulk(ids, function(error, response, context) {
 
    
    });

getAllDeals

Returns all deals. For more information on how to get all deals, see this tutorial.

function getAllDeals(input, callback)

Parameters

Example Usage

 
    var input = [];
        input['userId'] = 58;
        input['filterId'] = 58;
        input['stageId'] = 58;
        input['status'] = new Status2Enum(all_not_deleted);
        input['start'] = 0;
        input['limit'] = 58;
        input['sort'] = 'sort';
        input['ownedByYou'] = Object.keys(NumberBoolean)[0];
 
    controller.getAllDeals(input, function(error, response, context) {
 
    
    });

addADeal

Adds a new deal. Note that you can supply additional custom fields along with the request that are not described here. These custom fields are different for each Pipedrive account and can be recognized by long hashes as keys. To determine which custom fields exists, fetch the dealFields and look for 'key' values. For more information on how to add a deal, see this tutorial.

function addADeal(input, callback)

Parameters

Example Usage

 
    var input = [];
        input['contentType'] = 'Content-Type';
        input['body'] = {
        id : 21
    };
 
    controller.addADeal(input, function(error, response, context) {
 
    
    });

findDealsByName

Searches all deals by their title.

function findDealsByName(input, callback)

Parameters

Example Usage

 
    var input = [];
        input['term'] = 'term';
        input['personId'] = 58;
        input['orgId'] = 58;
 
    controller.findDealsByName(input, function(error, response, context) {
 
    
    });

getDealsSummary

Returns summary of all the deals.

function getDealsSummary(input, callback)

Parameters

Example Usage

 
    var input = [];
        input['status'] = Object.keys(status3)[0];
        input['filterId'] = 58;
        input['userId'] = 58;
        input['stageId'] = 58;
 
    controller.getDealsSummary(input, function(error, response, context) {
 
    
    });

getDealsTimeline

Returns open and won deals, grouped by defined interval of time set in a date-type dealField (field_key) — e.g. when month is the chosen interval, and 3 months are asked starting from January 1st, 2012, deals are returned grouped into 3 groups — January, February and March — based on the value of the given field_key.

function getDealsTimeline(input, callback)

Parameters

Example Usage

 
    var input = [];
        input['startDate'] = '2019-11-22';
        input['interval'] = Object.keys(interval2)[0];
        input['amount'] = 58;
        input['fieldKey'] = field_key;
        input['userId'] = 58;
        input['pipelineId'] = 58;
        input['filterId'] = 58;
        input['excludeDeals'] = Object.keys(NumberBoolean)[0];
        input['totalsConvertCurrency'] = totals_convert_currency;
 
    controller.getDealsTimeline(input, function(error, response, context) {
 
    
    });

deleteADeal

Marks a deal as deleted.

function deleteADeal(id, callback)

Parameters

Example Usage

 
    var id = 58;
 
    controller.deleteADeal(id, function(error, response, context) {
 
    
    });

getDetailsOfADeal

Returns details of a specific deal. Note that this also returns some additional fields which are not present when asking for all deals – such as deal age and stay in pipeline stages. Also note that custom fields appear as long hashes in the resulting data. These hashes can be mapped against the 'key' value of dealFields. For more information on how to get all details of a deal, see this tutorial.

function getDetailsOfADeal(id, callback)

Parameters

Example Usage

 
    var id = 58;
 
    controller.getDetailsOfADeal(id, function(error, response, context) {
 
    
    });

updateADeal

Updates the properties of a deal. For more information on how to update a deal, see this tutorial.

function updateADeal(input, callback)

Parameters

Example Usage

 
    var input = [];
        input['id'] = 58;
        input['title'] = 'title';
        input['value'] = 'value';
        input['currency'] = 'currency';
        input['userId'] = 58;
        input['personId'] = 58;
        input['orgId'] = 58;
        input['stageId'] = 58;
        input['status'] = Object.keys(Status)[0];
        input['probability'] = 58.5644835925496;
        input['lostReason'] = lost_reason;
        input['visibleTo'] = Object.keys(VisibleTo)[0];
 
    controller.updateADeal(input, function(error, response, context) {
 
    
    });

listActivitiesAssociatedWithADeal

Lists activities associated with a deal.

function listActivitiesAssociatedWithADeal(input, callback)

Parameters

Example Usage

 
    var input = [];
        input['id'] = 58;
        input['start'] = 58;
        input['limit'] = 58;
        input['done'] = Object.keys(NumberBoolean)[0];
        input['exclude'] = 'exclude';
 
    controller.listActivitiesAssociatedWithADeal(input, function(error, response, context) {
 
    
    });

createDuplicateDeal

Duplicate a deal

function createDuplicateDeal(id, callback)

Parameters

Example Usage

 
    var id = 58;
 
    controller.createDuplicateDeal(id, function(error, response, context) {
 
    
    });

listFilesAttachedToADeal

Lists files associated with a deal.

function listFilesAttachedToADeal(input, callback)

Parameters

Example Usage

 
    var input = [];
        input['id'] = 58;
        input['start'] = 58;
        input['limit'] = 58;
        input['includeDeletedFiles'] = Object.keys(NumberBoolean)[0];
        input['sort'] = 'sort';
 
    controller.listFilesAttachedToADeal(input, function(error, response, context) {
 
    
    });

listUpdatesAboutADeal

Lists updates about a deal.

function listUpdatesAboutADeal(input, callback)

Parameters

Example Usage

 
    var input = [];
        input['id'] = 58;
        input['start'] = 58;
        input['limit'] = 58;
 
    controller.listUpdatesAboutADeal(input, function(error, response, context) {
 
    
    });

listFollowersOfADeal

Lists the followers of a deal.

function listFollowersOfADeal(id, callback)

Parameters

Example Usage

 
    var id = 58;
 
    controller.listFollowersOfADeal(id, function(error, response, context) {
 
    
    });