Working with Deals in Pipedrive

Overview

The following operations allow you to work with deals. Click an operation name to see details on how to use it.

For a sample proxy service that illustrates how to work with deals, see Sample configuration.

Operation	Description
createDeal	Adds a new deal.
getDeal	Retrieves details of a specific deal.
listDealFollowers	Retrieves the followers of a deal.
listDeals	Retrieves all deals.
listDealsTimeline	Retrieves open and won deals, grouped by defined interval of time.
updateDeal	Updates the properties of a deal.
listDealProducts	Retrieves products attached to a deal.

Operation details

This section provides further details on the operations related to deals.

Adding a new deal

The createDeal operation adds a new deal.

createDeal

<pipedrive.createDeal>
	<title>{$ctx:title}</title>
	<customFields>{$ctx:customFields}</customFields>
	<value>{$ctx:value}</value>
	<currency>{$ctx:currency}</currency>
	<userId>{$ctx:userId}</userId>
	<personId>{$ctx:personId}</personId>
	<organizationId>{$ctx:organizationId}</organizationId>
	<stageId>{$ctx:stageId}</stageId>
	<status>{$ctx:status}</status>
	<lostReason>{$ctx:lostReason}</lostReason>
	<addedTime>{$ctx:addedTime}</addedTime>
	<visibility>{$ctx:visibility}</visibility>
	<prettyOutput>{$ctx:prettyOutput}</prettyOutput>
	<fields>{$ctx:fields}</fields>
</pipedrive.createDeal>

Properties

title: The title of the deal.
customFields: JSON object specifying the values for the deal's custom fields created in the account, keys for the object are the 40-character hashes assigned for the respective custom fields.
value: The value of the deal. If omitted, value will be set to 0.
currency: The currency of the deal, Accepts a 3-character currency code. If omitted, will be set to the default currency of the authorized user.
userId: The identifier of the user who will be marked as the owner of this deal. If omitted, the authorized user Identifier will be used.
personId: The identifier of the person this deal will be associated with.
organizationId: The identifier of the organization this deal will be associated with.
stageId: The identifier of the stage this deal will be placed in a pipeline. If omitted, the deal will be placed in the first stage of the default pipeline.
status: Specifies the status of the deal, possible values are Open, Won, Lost, Deleted, defaults to Open.
lostReason: Optional message about why the deal was lost (to be used when status=lost).
addedTime: Optional creation date and time of the deal in UTC. Requires admin user API token. Format: YYYY-MM-DD HH:MM:SS.
visibility: Visibility of the deal. If omitted, visibility will be set to the default visibility, possible values are 0,1,2.
prettyOutput: If the prettyOutput is specified as 1, will return an indented response of the output.
fields: The array of fields to be returned in the output.

Sample request

Following is a sample REST/JSON request that can be handled by the createDeal operation.

Sample Request for createDeal

{
	"apiToken":"39126d07e28ce7e3a62bc49b50ad51adc82b5f91",
	"apiUrl":"https://api.pipedrive.com",
	"title" : "testTitle",
	"customFields" : {"ea4c0246c80f5df831af9e8c48d1841b6a5f2886":"testQuoteId", "898f551845e6603dd1a0aa61186a04ed593bdd65":"testPotentialId"},
	"value" : "5400",
	"currency" : "LKR",
	"userId" : 545970,
	"personId" : 10,
	"organizationId" : 2,
	"stageId" : 2,
	"status" : "Lost",
	"lostReason" : "testReason",
	"addedTime" : "2015-05-01 11:12:13",
	"visibility" : 1,
	"prettyOutput":1,
	"fields":["id", "user_id"]
}

Retrieves details of a specific deal

The getDeal operation retrieves details of a specific deal.

getDeal

<pipedrive.getDeal>
    <id>{$ctx:id}</id>
    <prettyOutput>{$ctx:prettyOutput}</prettyOutput>
	<fields>{$ctx:fields}</fields>
</pipedrive.getDeal>

Properties

id: The unique identifier of the deal.
prettyOutput: If the prettyOutput is specified as 1, will return an indented response of the output.
fields: The array of fields to be returned in the output.

Sample request

Following is a sample REST/JSON request that can be handled by the getDeal operation.

Sample Request for getDeal

{
	"apiToken":"23e5036a3fbea622c27ec5fbc09cad17b97f1c04",
	"apiUrl":"https://api.pipedrive.com",
	"id":4,
	"prettyOutput":1,
	"fields":["id","title"]
}

Retrieving the followers of a deal

The listDealFollowers operation retrieves the followers of a deal.

listDealFollowers

<pipedrive.listDealFollowers>
     <id>{$ctx:id}</id>
	<prettyOutput>{$ctx:prettyOutput}</prettyOutput>
</pipedrive.listDealFollowers>

Properties

id: The unique identifier of the deal.
prettyOutput: If the prettyOutput is specified as 1, will return an indented response of the output.

Sample request

Following is a sample REST/JSON request that can be handled by the listDealFollowers operation.

Sample Request for listDealFollowers

{
	"apiToken":"23e5036a3fbea622c27ec5fbc09cad17b97f1c04",
	"apiUrl":"https://api.pipedrive.com",
	"id":2,
	"prettyOutput":1
}

Retrieving all deals

The listDeals operation retrieves all details.

listDeals

<pipedrive.listDeals>
    <limit>{$ctx:limit}</limit>
    <sort>{$ctx:sort}</sort>
    <filterId>{$ctx:filterId}</filterId>
    <start>{$ctx:start}</start>
    <prettyOutput>{$ctx:prettyOutput}</prettyOutput>
    <ownedByYou>{$ctx:ownedByYou}</ownedByYou>
	<fields>{$ctx:fields}</fields>
</pipedrive.listDeals>

Properties

limit: The number of items shown per page.
sort: The field names and sorting mode separated by comma(i.e.,field_name_1 ASC, field_name_2 DESC).
filterId: The unique identifier of the filter to be used.
start: The start of the pagination.
prettyOutput: If the prettyOutput is specified as 1, will return an indented response of the output.
ownedByYou: The boolean value to specify if only the deals owned by you to be returned.
fields: The array of fields to be returned in the output.

Sample request

Following is a sample REST/JSON request that can be handled by the listDeals operation.

Sample Request for listDeals

{
	"apiToken":"23e5036a3fbea622c27ec5fbc09cad17b97f1c04",
	"apiUrl":"https://api.pipedrive.com",
	"limit":1,
	"sort":["add_time asc", "update_time desc"],
	"filterId":"2",
	"start":0,
	"prettyOutput":1,
	"ownedByYou":true,
	"fields":["id","title"]
}

Retrieving open and won deals

The listDealsTimeline operation retrieves open and won deals, grouped by defined interval of time.

listDealsTimeline

<pipedrive.listDealsTimeline>
    <amount>{$ctx:amount}</amount>
    <startDate>{$ctx:startDate}</startDate>
    <currencyCode>{$ctx:currencyCode}</currencyCode>
    <filterId>{$ctx:filterId}</filterId>
    <interval>{$ctx:interval}</interval>
    <prettyOutput>{$ctx:prettyOutput}</prettyOutput>
    <userId>{$ctx:userId}</userId>
    <pipelineId>{$ctx:pipelineId}</pipelineId>
    <excludeDeals>{$ctx:excludeDeals}</excludeDeals>
    <fieldKey>{$ctx:fieldKey}</fieldKey>
	<fields>{$ctx:fields}</fields>
</pipedrive.listDealsTimeline>

Properties

amount: The number of given intervals, starting from start_date, to fetch, E.g.3 (months).
startDate: The date where first interval starts. Format: YYYY-MM-DD.
currencyCode: The three letter currency code of any of the supported currencies (for default currency set the value as 'default_currency').
filterId: The unique Identifier of the filter. If supplied only the deals matching the given filter will be returned.
interval: The type of interval. Can only contain one of the following values: day, week, month,quarter).
prettyOutput: If the prettyOutput is specified as 1, will return an indented response of the output.
userId: The unique Identifier of the user. If supplied only the deals matching the given user will be returned.
pipelineId: The unique Identifier of the pipeline. If supplied only the deals matching the given pipeline will be returned.
excludeDeals: The boolean value to indicate whether to exclude deals list or not.
fieldKey: The name of the date field by which to get deals by.
fields: The array of fields to be returned in the output.

Sample request

Following is a sample REST/JSON request that can be handled by the listDealsTimeline operation.

Sample Request for listDealsTimeline

{
	"apiToken":"23e5036a3fbea622c27ec5fbc09cad17b97f1c04",
	"apiUrl":"https://api.pipedrive.com",
	"amount":2,
	"startDate":"2015-03-23",
	"currencyCode":"default_currency",
	"filterId":1,
	"interval":"week",
	"prettyOutput":1,
	"userId":545982,
	"pipelineId":1,
	"excludeDeals":0,
	"fieldKey":"expected_close_date",
	"fields":["deals"]
}

Updating the properties of a deal

The updateDeal operation updates the properties of a deal.

updateDeal

<pipedrive.updateDeal>
	<id>{$ctx:id}</id>
	<title>{$ctx:title}</title>
	<value>{$ctx:value}</value>
	<currency>{$ctx:currency}</currency>
	<userId>{$ctx:userId}</userId>
	<personId>{$ctx:personId}</personId>
	<organizationId>{$ctx:organizationId}</organizationId>
	<stageId>{$ctx:stageId}</stageId>
	<status>{$ctx:status}</status>
	<lostReason>{$ctx:lostReason}</lostReason>
	<visibility>{$ctx:visibility}</visibility>
	<prettyOutput>{$ctx:prettyOutput}</prettyOutput>
	<fields>{$ctx:fields}</fields>
	<customFields>{$ctx:customFields}</customFields>
</pipedrive.updateDeal>

Properties

id: The identifier of the deal to be updated.
title:The title of the deal.
value: The value of the deal.
currency: The currency of the deal. Accepts a 3-character currency code.
userId: The Identifier of the user who will be marked as the owner of this deal.
personId: The Identifier of the person this deal will be associated with.
organizationId: The Identifier of the organization, the deal will be associated with.
stageId: The Identifier of the stage this deal will be placed in a pipeline.
status: The status of the deal, possible values are Open, Won, Lost and Deleted.
lostReason: The message about why the deal was lost, only to be used when the status is Lost.
visibility: Visibility of the deal. If omitted, visibility will not be changed, possible values are 0,1 and 2.
prettyOutput: If the prettyOutput is specified as 1, will return an indented response of the output.
fields: The array of fields to be returned in the output.
customFields: JSON Object specifying the values for the deal's custom fields created in the account, keys for the object are the 40-character hashes assigned for the respective custom fields.

Sample request

Following is a sample REST/JSON request that can be handled by the updateDeal operation.

Sample Request for updateDeal

{
	"apiToken":"39126d07e28ce7e3a62bc49b50ad51adc82b5f91",
	"apiUrl":"https://api.pipedrive.com",
	"id":66,
	"title" : "myDealTitleUpdated",
	"value" : "5455",
	"currency" : "LKR",
	"userId" : 545970,
	"personId" : 8,
	"organizationId" : 2,
	"stageId" : 2,
	"status" : "Lost",
	"lostReason" : "testLostReasonUpdated",
	"visibility" : 1,
	"customFields" : {"ea4c0246c80f5df831af9e8c48d1841b6a5f2886":"testQuoteIdUpdated", "898f551845e6603dd1a0aa61186a04ed593bdd65":"testPotentialIdUpdated"},
	"prettyOutput":1,
	"fields":["id","user_id","person_id"]
}

Retrieves products attached to a deal

The listDealProducts operation retrieves the products attached to a deal

listDealProducts

<pipedrive.listDealProducts>
	<prettyOutput>{$ctx:prettyOutput}</prettyOutput>
    <fields>{$ctx:fields}</fields>
    <id>{$ctx:id}</id>
    <start>{$ctx:start}</start>
    <limit>{$ctx:limit}</limit>
    <includeProductData>{$ctx:includeProductData}</includeProductData>
</pipedrive.listDealProducts>

Properties

prettyOutput: If it is specified as '1', it will return an indented response of the output.
fields:The array of fields to be returned in the output.
id: The unique identifier of a deal to retrieve it's attached products.
start: The start of the pagination.
limit: The number of items shown per page.
includeProductData: Indicates whether to fetch product data along with each attached product (1) or not (0, default).

Sample request

Following is a sample REST/JSON request that can be handled by the listDealProducts operation.

Sample Request for listDealProducts

{
	"apiToken":"39126d07e28ce7e3a62bc49b50ad51adc82b5f91",
	"apiUrl":"https://api.pipedrive.com",	
	"prettyOutput":1,
	"fields":["item_price","add_time"],
	"id": 77,	
	"start":0,
	"limit":2,
	"includeProductData":1
}

Sample configuration

Following is a sample proxy service that illustrates how to connect to Pipedrive with the init operation and use the createDeal operation. The sample request for this proxy can be found in createDeal sample request. You can use this sample as a template for using other operations in this category.

Sample Proxy

<?xml version="1.0" encoding="UTF-8"?>
<proxy xmlns="http://ws.apache.org/ns/synapse" name="pipedrive_createDeal" transports="https,http" statistics="disable" trace="disable" startOnLoad="true">
	<target>
		<inSequence>
			<property name="apiUrl" expression="json-eval($.apiUrl)" />
			<property name="apiToken" expression="json-eval($.apiToken)" />
			<property name="title" expression="json-eval($.title)" />
			<property name="customFields" expression="json-eval($.customFields)" />
			<property name="value" expression="json-eval($.value)" />
			<property name="currency" expression="json-eval($.currency)" />
			<property name="userId" expression="json-eval($.userId)" />
			<property name="personId" expression="json-eval($.personId)" />
			<property name="organizationId" expression="json-eval($.organizationId)" />
			<property name="stageId" expression="json-eval($.stageId)" />
			<property name="status" expression="json-eval($.status)" />
			<property name="lostReason" expression="json-eval($.lostReason)" />
			<property name="addedTime" expression="json-eval($.addedTime)" />
			<property name="visibility" expression="json-eval($.visibility)" />
			<property name="prettyOutput" expression="json-eval($.prettyOutput)"/>
			<property name="fields" expression="json-eval($.fields)"/>
			<pipedrive.init>
				<apiToken>{$ctx:apiToken}</apiToken>
				<apiUrl>{$ctx:apiUrl}</apiUrl>
			</pipedrive.init>
			<pipedrive.createDeal>
				<title>{$ctx:title}</title>
				<customFields>{$ctx:customFields}</customFields>
				<value>{$ctx:value}</value>
				<currency>{$ctx:currency}</currency>
				<userId>{$ctx:userId}</userId>
				<personId>{$ctx:personId}</personId>
				<organizationId>{$ctx:organizationId}</organizationId>
				<stageId>{$ctx:stageId}</stageId>
				<status>{$ctx:status}</status>
				<lostReason>{$ctx:lostReason}</lostReason>
				<addedTime>{$ctx:addedTime}</addedTime>
				<visibility>{$ctx:visibility}</visibility>
				<prettyOutput>{$ctx:prettyOutput}</prettyOutput>
				<fields>{$ctx:fields}</fields>
			</pipedrive.createDeal>
			<respond />
		</inSequence>
		<outSequence>
			<send />
		</outSequence>
	</target>
	<description />
</proxy>

WSO2 ESB Connectors Documentation

Working with Deals in Pipedrive

Overview

Operation details

Adding a new deal

Properties

Sample request

Related Pipedrive documentation

Retrieves details of a specific deal

Properties

Sample request

Related Pipedrive documentation

Retrieving the followers of a deal

Properties

Sample request

Related Pipedrive documentation

Retrieving all deals

Properties

Sample request

Related Pipedrive documentation

Retrieving open and won deals

Properties

Sample request

Related Pipedrive documentation

Updating the properties of a deal

Properties

Sample request

Related Pipedrive documentation

Retrieves products attached to a deal

Properties

Sample request

Related Pipedrive documentation

Sample configuration