Deals
Deals represent ongoing, lost or won sales to an organization or to a person. Each deal has a monetary value and must be placed in a stage. Deals can be owned by a user, and followed by one or many users. Each deal consists of standard data fields but can also contain a number of custom fields. The custom fields can be recognized by long hashes as keys. These hashes can be mapped against DealField.key. The corresponding label for each such custom field can be obtained from DealField.name.
Get all deals
/v1/deals
Returns all deals. For more information, see the tutorial for getting all deals.
Query parameters
user_id
integer
If supplied, only deals matching the given user will be returned. However, filter_id and owned_by_you takes precedence over user_id when supplied.
filter_id
integer
The ID of the filter to use
stage_id
integer
If supplied, only deals within the given stage will be returned
status
string
Only fetch deals with a specific status. If omitted, all not deleted deals are returned. If set to deleted, deals that have been deleted up to 30 days ago will be included.
Default
all_not_deleted
Values
open
won
lost
deleted
all_not_deleted
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
sort
string
The field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys).
owned_by_you
number
When supplied, only deals owned by you are returned. However, filter_id takes precedence over owned_by_you when both are supplied.
Values
0
1
Response
OK
Expand all
Copy code- true
- [ ... ]▶
- { ... }▶
- { ... }▶
Get all deals (BETA)
/v1/deals/collection
Returns all deals. This is a cursor-paginated endpoint that is currently in BETA. For more information, please refer to our documentation on pagination. Please note that only global admins (those with global permissions) can access these endpoints. Users with regular permissions will receive a 403 response. Read more about global permissions here.
Query parameters
cursor
string
For pagination, the marker (an opaque string value) representing the first item on the next page
limit
integer
For pagination, the limit of entries to be returned. If not provided, 100 items will be returned. Please note that a maximum value of 500 is allowed.
since
string
The time boundary that points to the start of the range of data. Datetime in ISO 8601 format. E.g. 2022-11-01 08:55:59. Operates on the update_time field.
until
string
The time boundary that points to the end of the range of data. Datetime in ISO 8601 format. E.g. 2022-11-01 08:55:59. Operates on the update_time field.
user_id
integer
If supplied, only deals matching the given user will be returned
stage_id
integer
If supplied, only deals within the given stage will be returned
status
string
Only fetch deals with a specific status. If omitted, all not deleted deals are returned. If set to deleted, deals that have been deleted up to 30 days ago will be included.
Values
open
won
lost
deleted
Response
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
Search deals
/v1/deals/search
Searches all deals by title, notes and/or custom fields. This endpoint is a wrapper of /v1/itemSearch with a narrower OAuth scope. Found deals can be filtered by the person ID and the organization ID.
Query parameters
term
string
required
The search term to look for. Minimum 2 characters (or 1 if using exact_match). Please note that the search term has to be URL encoded.
fields
string
A comma-separated string array. The fields to perform the search from. Defaults to all of them. Only the following custom field types are searchable: address, varchar, text, varchar_auto, double, monetary and phone. Read more about searching by custom fields here.
Values
custom_fields
notes
title
exact_match
boolean
When enabled, only full exact matches against the given term are returned. It is not case sensitive.
person_id
integer
Will filter deals by the provided person ID. The upper limit of found deals associated with the person is 2000.
organization_id
integer
Will filter deals by the provided organization ID. The upper limit of found deals associated with the organization is 2000.
status
string
Will filter deals by the provided specific status. open = Open, won = Won, lost = Lost. The upper limit of found deals associated with the status is 2000.
Values
open
won
lost
include_fields
string
Supports including optional fields in the results which are not provided by default
Values
deal.cc_email
start
integer
Pagination start. Note that the pagination is based on main results and does not include related items when using search_for_related_items parameter.
Default
0
limit
integer
Items shown per page
Response
OK
Expand allCopy code- true
- { ... }▶
- { ... }▶
Get deals summary
/v1/deals/summary
Returns a summary of all the deals.
Query parameters
status
string
Only fetch deals with a specific status. open = Open, won = Won, lost = Lost
Values
open
won
lost
filter_id
integer
user_id will not be considered. Only deals matching the given filter will be returned.
user_id
integer
Only deals matching the given user will be returned. user_id will not be considered if you use filter_id.
stage_id
integer
Only deals within the given stage will be returned
Response
OK
Expand allCopy code- true
- { ... }▶
Get deals timeline
/v1/deals/timeline
Returns open and won deals, grouped by a 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.
Query parameters
start_date
string
required
The date when the first interval starts. Format: YYYY-MM-DD
Format
date
interval
string
required
The type of the interval
| Value | Description |
|---|---|
day | Day |
week | A full week (7 days) starting from start_date |
month | A full month (depending on the number of days in given month) starting from start_date |
quarter | A full quarter (3 months) starting from start_date |
Values
day
week
month
quarter
amount
integer
required
The number of given intervals, starting from start_date, to fetch. E.g. 3 (months).
field_key
string
required
The date field key which deals will be retrieved from
user_id
integer
If supplied, only deals matching the given user will be returned
pipeline_id
integer
If supplied, only deals matching the given pipeline will be returned
filter_id
integer
If supplied, only deals matching the given filter will be returned
exclude_deals
number
Whether to exclude deals list (1) or not (0). Note that when deals are excluded, the timeline summary (counts and values) is still returned.
Values
0
1
totals_convert_currency
string
The 3-letter currency code of any of the supported currencies. When supplied, totals_converted is returned per each interval which contains the currency-converted total amounts in the given currency. You may also set this parameter to default_currency in which case the user's default currency is used.
Response
OK
Expand allCopy code- true
- { ... }▶
Get details of a deal
/v1/deals/{id}
Returns the 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, see the tutorial for getting details of a deal.
Path parameters
id
integer
required
The ID of the deal
Response
OK
Expand allCopy code- true
- { ... }▶
- { ... }▶
- { ... }▶
List activities associated with a deal
/v1/deals/{id}/activities
Lists activities associated with a deal.
Path parameters
id
integer
required
The ID of the deal
Query parameters
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
done
number
Whether the activity is done or not. 0 = Not done, 1 = Done. If omitted, returns both Done and Not done activities.
Values
0
1
exclude
string
A comma-separated string of activity IDs to exclude from result
Response
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
- { ... }▶
List files attached to a deal
/v1/deals/{id}/files
Lists files associated with a deal.
Path parameters
id
integer
required
The ID of the deal
Query parameters
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
sort
string
The field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys). Supported fields: id, user_id, deal_id, person_id, org_id, product_id, add_time, update_time, file_name, file_type, file_size, comment.
Response
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
List updates about a deal
/v1/deals/{id}/flow
Lists updates about a deal.
Path parameters
id
integer
required
The ID of the deal
Query parameters
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
all_changes
string
Whether to show custom field updates or not. 1 = Include custom field changes. If omitted returns changes without custom field updates.
items
string
A comma-separated string for filtering out item specific updates. (Possible values - call, activity, plannedActivity, change, note, deal, file, dealChange, personChange, organizationChange, follower, dealFollower, personFollower, organizationFollower, participant, comment, mailMessage, mailMessageWithAttachment, invoice, document, marketing_campaign_stat, marketing_status_change)
Response
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
- { ... }▶
List followers of a deal
/v1/deals/{id}/followers
Lists the followers of a deal.
Path parameters
id
integer
required
The ID of the deal
Response
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
List mail messages associated with a deal
/v1/deals/{id}/mailMessages
Lists mail messages associated with a deal.
Path parameters
id
integer
required
The ID of the deal
Query parameters
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
Response
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
List participants of a deal
/v1/deals/{id}/participants
Lists the participants associated with a deal.
If a company uses the Campaigns product, then this endpoint will also return the data.marketing_status field.
Path parameters
id
integer
required
The ID of the deal
Query parameters
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
Response
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
- { ... }▶
List permitted users
/v1/deals/{id}/permittedUsers
Lists the users permitted to access a deal.
Path parameters
id
integer
required
The ID of the deal
Response
OK
Expand allCopy code- true
- { ... }▶
List all persons associated with a deal
/v1/deals/{id}/persons
Lists all persons associated with a deal, regardless of whether the person is the primary contact of the deal, or added as a participant.
If a company uses the Campaigns product, then this endpoint will also return the data.marketing_status field.
Path parameters
id
integer
required
The ID of the deal
Query parameters
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
Response
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
- { ... }▶
List products attached to a deal
/v1/deals/{id}/products
Lists products attached to a deal.
Path parameters
id
integer
required
The ID of the deal
Query parameters
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
include_product_data
number
Whether to fetch product data along with each attached product (1) or not (0, default)
Values
0
1
Response
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
- { ... }▶
Add a deal
/v1/deals
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, see the tutorial for adding a deal.
Body parameters
application/json
title
string
required
The title of the deal
value
string
The value of the deal. If omitted, value will be set to 0.
currency
string
The currency of the deal. Accepts a 3-character currency code. If omitted, currency will be set to the default currency of the authorized user.
user_id
integer
The ID of the user which will be the owner of the created deal. If not provided, the user making the request will be used.
person_id
integer
The ID of a person which this deal will be linked to. If the person does not exist yet, it needs to be created first. This property is required unless org_id is specified.
org_id
integer
The ID of an organization which this deal will be linked to. If the organization does not exist yet, it needs to be created first. This property is required unless person_id is specified.
pipeline_id
integer
The ID of the pipeline this deal will be added to. By default, the deal will be added to the first stage of the specified pipeline. Please note that pipeline_id and stage_id should not be used together as pipeline_id will be ignored.
stage_id
integer
The ID of the stage this deal will be added to. Please note that a pipeline will be assigned automatically based on the stage_id. If omitted, the deal will be placed in the first stage of the default pipeline.
status
string
open = Open, won = Won, lost = Lost, deleted = Deleted. If omitted, status will be set to open.
Values
open
won
lost
deleted
add_time
string
The optional creation date & time of the deal in UTC. Requires admin user API token. Format: YYYY-MM-DD HH:MM:SS
expected_close_date
string
The expected close date of the deal. In ISO 8601 format: YYYY-MM-DD.
Format
date
probability
number
The success probability percentage of the deal. Used/shown only when deal_probability for the pipeline of the deal is enabled.
lost_reason
string
The optional message about why the deal was lost (to be used when status = lost)
visible_to
string
The visibility of the deal. If omitted, the visibility will be set to the default visibility setting of this item type for the authorized user. Read more about visibility groups here.
Essential / Advanced plan
| Value | Description |
|---|---|
1 | Owner & followers |
3 | Entire company |
Professional / Enterprise plan
| Value | Description |
|---|---|
1 | Owner only |
3 | Owner's visibility group |
5 | Owner's visibility group and sub-groups |
7 | Entire company |
Values
1
3
5
7
Response
Created
Expand allCopy code- true
- { ... }▶
- { ... }▶
Duplicate deal
/v1/deals/{id}/duplicate
Duplicates a deal.
Path parameters
id
integer
required
The ID of the deal
Response
OK
Expand allCopy code- true
- { ... }▶
Add a follower to a deal
/v1/deals/{id}/followers
Adds a follower to a deal.
Path parameters
id
integer
required
The ID of the deal
Body parameters
application/json
user_id
integer
required
The ID of the user
Response
OK
Expand allCopy code- true
- { ... }▶
Add a participant to a deal
/v1/deals/{id}/participants
Adds a participant to a deal.
Path parameters
id
integer
required
The ID of the deal
Body parameters
application/json
person_id
integer
required
The ID of the person
Response
OK
Expand allCopy code- true
- { ... }▶
- { ... }▶
Add a product to a deal
/v1/deals/{id}/products
Adds a product to a deal, creating a new item called a deal-product.
Path parameters
id
integer
required
The ID of the deal
Body parameters
application/json
product_id
integer
required
The ID of the product to use
item_price
number
required
The price at which this product will be added to the deal
quantity
integer
required
Quantity – e.g. how many items of this product will be added to the deal
discount
number
The value of the discount. The discount_type field can be used to specify whether the value is an amount or a percentage.
Default
0
discount_type
string
The type of the discount's value.
Default
percentage
Values
percentage
amount
duration
number
The duration of the product. If omitted, will be set to 1.
Default
1
duration_unit
string
The unit duration of the product
Values
hourly
daily
weekly
monthly
yearly
product_variation_id
integer
The ID of the product variation to use. When omitted, no variation will be used.
comments
string
A textual comment associated with this product-deal attachment
tax
number
The tax percentage
Default
0
tax_method
string
The tax option to be applied to the products. When using inclusive, the tax percentage will already be included in the price. When using exclusive, the tax will not be included in the price. When using none, no tax will be added. Use the tax field for defining the tax percentage amount. By default, the user setting value for tax options will be used. Changing this in one product affects the rest of the products attached to the deal.
Values
exclusive
inclusive
none
enabled_flag
boolean
Whether the product is enabled for a deal or not. This makes it possible to add products to a deal with a specific price and discount criteria, but keep them disabled, which refrains them from being included in the deal value calculation. When omitted, the product will be marked as enabled by default.
Default
true
Response
OK
Expand allCopy code- true
- { ... }▶
Update a deal
/v1/deals/{id}
Updates the properties of a deal. For more information, see the tutorial for updating a deal.
Path parameters
id
integer
required
The ID of the deal
Body parameters
application/json
title
string
The title of the deal
value
string
The value of the deal.
currency
string
The currency of the deal. Accepts a 3-character currency code.
user_id
integer
The ID of the user which will be the new owner of the deal.
person_id
integer
The ID of a person which this deal will be linked to. If the person does not exist yet, it needs to be created first.
org_id
integer
The ID of an organization which this deal will be linked to. If the organization does not exist yet, it needs to be created first.
pipeline_id
integer
The ID of the pipeline this deal will be added to. By default, the deal will be added to the first stage of the specified pipeline. Please note that pipeline_id and stage_id should not be used together as pipeline_id will be ignored.
stage_id
integer
The ID of the stage this deal will be added to. Please note that a pipeline will be assigned automatically based on the stage_id.
status
string
open = Open, won = Won, lost = Lost, deleted = Deleted.
Values
open
won
lost
deleted
expected_close_date
string
The expected close date of the deal. In ISO 8601 format: YYYY-MM-DD.
Format
date
probability
number
The success probability percentage of the deal. Used/shown only when deal_probability for the pipeline of the deal is enabled.
lost_reason
string
The optional message about why the deal was lost (to be used when status = lost)
visible_to
string
The visibility of the deal. If omitted, the visibility will be set to the default visibility setting of this item type for the authorized user. Read more about visibility groups here.
Essential / Advanced plan
| Value | Description |
|---|---|
1 | Owner & followers |
3 | Entire company |
Professional / Enterprise plan
| Value | Description |
|---|---|
1 | Owner only |
3 | Owner's visibility group |
5 | Owner's visibility group and sub-groups |
7 | Entire company |
Values
1
3
5
7
Response
OK
Expand allCopy code- true
- { ... }▶
- { ... }▶
Merge two deals
/v1/deals/{id}/merge
Merges a deal with another deal. For more information, see the tutorial for merging two deals.
Path parameters
id
integer
required
The ID of the deal
Body parameters
application/json
merge_with_id
integer
required
The ID of the deal that the deal will be merged with
Response
OK
Expand allCopy code- true
- { ... }▶
Update the product attached to a deal
/v1/deals/{id}/products/{product_attachment_id}
Updates the details of the product that has been attached to a deal.
Path parameters
id
integer
required
The ID of the deal
product_attachment_id
integer
required
The ID of the deal-product (the ID of the product attached to the deal)
Body parameters
application/json
product_id
integer
The ID of the product to use
item_price
number
The price at which this product will be added to the deal
quantity
integer
How many items of this product will be added to the deal
discount
number
The value of the discount. The discount_type field can be used to specify whether the value is an amount or a percentage.
Default
0
discount_type
string
The type of the discount's value.
Default
percentage
Values
percentage
amount
duration
number
The duration of the product
Default
1
duration_unit
string
The unit duration of the product
Values
hourly
daily
weekly
monthly
yearly
product_variation_id
integer
The ID of the product variation to use. When omitted, no variation will be used.
comments
string
A textual comment associated with this product-deal attachment
tax
number
The tax percentage
Default
0
tax_method
string
The tax option to be applied to the products. When using inclusive, the tax percentage will already be included in the price. When using exclusive, the tax will not be included in the price. When using none, no tax will be added. Use the tax field for defining the tax percentage amount.
Values
exclusive
inclusive
none
enabled_flag
boolean
Whether the product is enabled for a deal or not. This makes it possible to add products to a deal with a specific price and discount criteria, but keep them disabled, which refrains them from being included in the deal value calculation. When omitted, the product will be marked as enabled by default.
Default
true
Response
OK
Expand allCopy code- true
- { ... }▶
Delete multiple deals in bulk
/v1/deals
Marks multiple deals as deleted. After 30 days, the deals will be permanently deleted.
Query parameters
ids
string
required
The comma-separated IDs that will be deleted
Response
OK
Expand allCopy code- true
- { ... }▶
Delete a deal
/v1/deals/{id}
Marks a deal as deleted. After 30 days, the deal will be permanently deleted.
Path parameters
id
integer
required
The ID of the deal
Response
OK
Expand allCopy code- true
- { ... }▶
Delete a follower from a deal
/v1/deals/{id}/followers/{follower_id}
Deletes a follower from a deal.
Path parameters
id
integer
required
The ID of the deal
follower_id
integer
required
The ID of the follower
Response
OK
Expand allCopy code- true
- { ... }▶
Delete a participant from a deal
/v1/deals/{id}/participants/{deal_participant_id}
Deletes a participant from a deal.
Path parameters
id
integer
required
The ID of the deal
deal_participant_id
integer
required
The ID of the participant of the deal
Response
OK
Expand allCopy code- true
- { ... }▶
Delete an attached product from a deal
/v1/deals/{id}/products/{product_attachment_id}
Deletes a product attachment from a deal, using the product_attachment_id.
Path parameters
id
integer
required
The ID of the deal
product_attachment_id
integer
required
The product attachment ID
Response
OK
Expand allCopy code- true
- { ... }▶
