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 you with basic functionality for operating with objects such as Deals, Persons, Organizations, Products and much more, without having to worry about the underlying networking stack and actual HTTPS requests.
Installation
npm install pipedrive
Roadmap & known issues
API Documentation
The Pipedrive REST API documentation can be found at https://developers.pipedrive.com/v1
Testing & Quality
To run unit tests, execute
npm run test
To run integration tests, execute
export PIPEDRIVE_API_TOKEN=YOUR_API_TOKEN
npm run test:integration
Important! Integration tests will add data to the account, so please run with caution!
Licence
This Pipedrive API client is distributed under the MIT licence.
Contribution
- Run unit and integration tests
- Make PR
How to use
With a pre-set API token:
var Pipedrive = require('pipedrive');
var pipedrive = new Pipedrive.Client('YOUR_API_TOKEN_HERE', { strictMode: true });
A simple "Hello world" that lists some deals
Here's a quick example that will list some deals from your Pipedrive account:
var Pipedrive = require('pipedrive');
var pipedrive = new Pipedrive.Client('YOUR_API_TOKEN_HERE', { strictMode: true });
pipedrive.Deals.getAll({}, function(err, deals) {
if (err) throw err;
for (var i = 0; i < deals.length; i++) {
console.log(deals[i].title + ' (worth ' + deals[i].value + ' ' + deals[i].currency + ')');
}
});
Supported objects
- Activities
- ActivityTypes
- Authorizations
- Currencies
- CompanyFeatures,
- CompanySettings,
- Deals
- DealFields
- Files
- Filters
- Goals
- Notes
- Organizations
- OrganizationFields
- PermissionSets
- Persons
- PersonFields
- Pipelines
- Products
- ProductFields
- Roles
- SearchResults
- Stages
- Users
- Webhooks
Supported operations for object collections
pipedrive.{Object}.add (data, [fn callback])
Add an object. Returns error, data
to the callback where data contains the id
property of the newly created item.
pipedrive.{Object}.get (id, [fn callback])
Get specific object. Returns error, object, additionalData, rawRequest, rawResponse, relatedObjects
pipedrive.{Object}.update (id, data, [fn callback])
Update an object. Returns error
in case of an error to the callback.
pipedrive.{Object}.getAll (params, [fn callback])
Get all objects, optionally passing additional parameters (such as filter_id
in case of deals, persons and organizations). Returns error, objects
to the callback function where objects is a collection (array) of objects.
pipedrive.{Object}.remove (id, [fn callback])
Delete an object with a specifc ID. Returns error
in case of an error to the callback.
pipedrive.{Object}.removeMany ([Array ids], [fn callback])
Delete multiple objects using an array of IDs. Returns error
in case of an error to the callback.
pipedrive.{Object}.merge (whichId, withId, [fn callback])
Merge two objects of the same kind. Returns error
in case of an error to the callback. Merge is only supported for the following objects:
- Persons
- Organizations
pipedrive.{Object}.find (params, [fn callback])
Find objects of certain kind by their name/title, using term
property supplied inside params object. Supported for:
- Deals
- Persons
- Organizations
- Users
Supported operations for each object
{object}.get(fieldName)
Returns the value of [fieldName] of the object.
{object}.set(fieldName, newValue)
Sets a new value of [fieldName] of the object. Returns {object}.
{object}.save([fn callback])
Updates the state of the {object} in Pipedrive via the API. Returns {object}.
{object}.remove([fn callback])
Deletes the {object} in Pipedrive via the API. Returns error
in case of an error to the callback.
{object}.merge(withId, [fn callback])
Merges the {object} with another object of the same kind with the ID given as withId
. Returns error
in case of error to the callback. Merge is only supported for the following objects:
- Persons
- Organizations
Operations with nested objects
Adding a product to a deal
To add a product to a deal, simply invoke the addProduct
method on a deal object.
pipedrive.Deals.get(1, function(err, deal) {
if (err) throw err;
deal.addProduct({ product_id: 1, quantity: 5, item_price: 10, discount: 20 }, function(addErr, addData) {
if (addErr) throw addErr;
console.log('Product 1 was added to deal 1', addData);
});
})
You can add multiple products with a single request, too.
To add multiple products with a single request, make the first argument of deal's addProduct
method (as shown above) an array, e.g. [{ product_id: 1, quantity: 5, discount: 0 }, { product_id: 1, quantity: 2, discount: 20 }]
. This will add two product rows to a deal — one with a quantity of 5 and with no discount, the latter will add a separate row for the same product but with a quantity of 2 and no discount.
Updating a deal product
pipedrive.Deals.get(deal_id, function(err, deal) {
if (err) throw err;
deal.getProducts(function(productsErr, attachedProducts) {
if (productsErr) throw productsErr;
attachedProducts.forEach(function(attachedProduct) {
deal.updateProduct({ id: attachedProduct.id, quantity: 5, discount: 20 }, function(updateErr, updateData) {
if (updateErr) throw updateErr;
console.log('Product was updated', updateData);
});
});
});
})
Updating multiple deal products in one request is not supported yet.
Delete a product from a deal
pipedrive.Deals.get(deal_id, function(err, deal) {
if (err) throw err;
deal.getProducts(function(productsErr, attachedProducts) {
if (productsErr) throw productsErr;
attachedProducts.forEach(function(attachedProduct) {
deal.deleteProduct({ id: attachedProduct.id }, function(removeErr, removeSuccess) {
if (!removeErr) console.log('Removed product ' + attachedProduct.product_id + ' from deal 1');
});
});
});
})
Search for field value matches
There is an additional method to perform the SearchResults/field
search. This can be used for field-value searches.
The following example searches for deals that match the condition where org_id=123
pipedrive.SearchResults.field({
term: "123",
exact_match: true,
field_key: "org_id",
field_type: "dealField",
return_item_ids: true
}), callback);
- term — the string you are searching for from field values
- exact_match (optional, default false) — whether the term you supply is the entire and exact match you are looking for (if set to false, partial results are also considered a match)
- field_key — name of the field you are searching from
- field_type — type of the field you are searching from (supported types: dealField, personField, organizationField, productField)
- return_item_ids (optional, default false) — if set to true, individual items that have the matching term in the given field are given; if set to false, the different distinct values that match your search term across all different values in the gievn field are given. Usually you would want this to be set to true. However, for searching across autocomplete_text type fields (such as lost_reason of dealFields), you might want to show different values that pre-exist already.
- start (optional, default 0) – results pagination start
- limit (optional, default 100) — results pagination limit
Retrieve all records for a given object type:
You can request all entries for an valid object using getAll(object, callback)
pipedrive.getAll('Organizatons', function (err, collection) {
// collection contains all Organizations
});
pipedrive.getAll('Persons', function (err, collection) {
// collection contains all Persons
});
Examples
Get 15 first deals using the first deals filter
var Pipedrive = require('pipedrive');
var pipedrive = new Pipedrive.Client('PUT_YOUR_API_TOKEN_HERE', { strictMode: true });
pipedrive.Filters.getAll({ type: 'deals' }, function(filtersListErr, filtersList) {
if (filtersList.length > 0) {
pipedrive.Deals.getAll({ filter_id: filtersList[0].get('id'), start: 0, limit: 15 }, function(dealsListErr, dealsList) {
dealsList.forEach(function(deal) {
console.log(deal.get('title') + ' (worth ' + deal.get('value') + ' ' + deal.get('currency') + ')');
});
})
}
});