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 |
---|---|
Adds a new deal. | |
1Working with Deals in Pipedrive | Retrieves details of a specific deal. |
1Working with Deals in Pipedrive | Retrieves the followers of a deal. |
1Working with Deals in Pipedrive | Retrieves all deals. |
1Working with Deals in Pipedrive | Retrieves open and won deals, grouped by defined interval of time. |
1Working with Deals in Pipedrive | Updates the properties of a deal. |
1Working with Deals in Pipedrive | 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.
<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
The title of the deal.title:
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.
{ "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"] }
Related Pipedrive documentation
https://developers.pipedrive.com/v1#methods-Deals
Retrieves details of a specific deal
The getDeal
operation retrieves details of a specific deal.
<pipedrive.getDeal> <id>{$ctx:id}</id> <prettyOutput>{$ctx:prettyOutput}</prettyOutput> <fields>{$ctx:fields}</fields> </pipedrive.getDeal>
Properties
The unique identifier of the deal.id:
If the prettyOutput is specified as 1, will return an indented response of the output.prettyOutput:
The array of fields to be returned in the output.fields:
Sample request
Following is a sample REST/JSON request that can be handled by the getDeal
operation.
{ "apiToken":"23e5036a3fbea622c27ec5fbc09cad17b97f1c04", "apiUrl":"https://api.pipedrive.com", "id":4, "prettyOutput":1, "fields":["id","title"] }
Related Pipedrive documentation
https://developers.pipedrive.com/v1#methods-Deals
Retrieving the followers of a deal
The
operation retrieves the followers of a deal.listDealFollowers
<pipedrive.listDealFollowers> <id>{$ctx:id}</id> <prettyOutput>{$ctx:prettyOutput}</prettyOutput> </pipedrive.listDealFollowers>
Properties
id:
If the prettyOutput is specified as 1, will return an indented response of the output.prettyOutput:
Sample request
Following is a sample REST/JSON request that can be handled by the
operation.listDealFollowers
{ "apiToken":"23e5036a3fbea622c27ec5fbc09cad17b97f1c04", "apiUrl":"https://api.pipedrive.com", "id":2, "prettyOutput":1 }
Related Pipedrive documentation
https://developers.pipedrive.com/v1#methods-Deals
Retrieving all deals
The listDeals
operation retrieves all details.
<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
The number of items shown per page.limit:
The field names and sorting mode separated by comma(i.e.,field_name_1 ASC, field_name_2 DESC).sort:
The unique identifier of the filter to be used.filterId:
The start of the pagination.start:
If the prettyOutput is specified as 1, will return an indented response of the output.prettyOutput:
The boolean value to specify if only the deals owned by you to be returned.ownedByYou:
The array of fields to be returned in the output.fields:
Sample request
Following is a sample REST/JSON request that can be handled by the
operation.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"] }
Related Pipedrive documentation
https://developers.pipedrive.com/v1#methods-Deals
Retrieving open and won deals
The
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
operation.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"] }
Related Pipedrive documentation
https://developers.pipedrive.com/v1#methods-Deals
Updating the properties of a deal
The updateDeal operation updates the properties of a deal.
<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
operation.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"] }
Related Pipedrive documentation
https://developers.pipedrive.com/v1#methods-Deals
Retrieves products attached to a deal
The listDealProducts operation retrieves the products attached to a deal
<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
operation.listDealProducts
{ "apiToken":"39126d07e28ce7e3a62bc49b50ad51adc82b5f91", "apiUrl":"https://api.pipedrive.com", "prettyOutput":1, "fields":["item_price","add_time"], "id": 77, "start":0, "limit":2, "includeProductData":1 }
Related Pipedrive documentation
https://developers.pipedrive.com/v1#methods-Deals
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.
<?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>