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
.
/v1/deals
Returns all deals. For more information, see the tutorial for getting all deals.
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
OK
/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.
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
OK
/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.
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.
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.
Values
true
false
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
OK
/v1/deals/summary
Returns a summary of all the deals.
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
OK
/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
.
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.
OK
/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.
id
integer
required
The ID of the deal
OK
/v1/deals/{id}/activities
Lists activities associated with a deal.
id
integer
required
The ID of the deal
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
OK
/v1/deals/{id}/files
Lists files associated with a deal.
id
integer
required
The ID of the deal
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
.
OK
/v1/deals/{id}/flow
Lists updates about a deal.
id
integer
required
The ID of the deal
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)
OK
/v1/deals/{id}/followers
Lists the followers of a deal.
id
integer
required
The ID of the deal
OK
/v1/deals/{id}/mailMessages
Lists mail messages associated with a deal.
id
integer
required
The ID of the deal
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
OK
/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.
id
integer
required
The ID of the deal
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
OK
/v1/deals/{id}/permittedUsers
Lists the users permitted to access a deal.
id
integer
required
The ID of the deal
OK
/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.
id
integer
required
The ID of the deal
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
OK
/v1/deals/{id}/products
Lists products attached to a deal.
id
integer
required
The ID of the deal
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
OK
/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.
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
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.
Value | Description |
---|---|
1 | Owner & followers |
3 | Entire company |
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
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
Created
/v1/deals/{id}/duplicate
Duplicates a deal.
id
integer
required
The ID of the deal
OK
/v1/deals/{id}/followers
Adds a follower to a deal.
id
integer
required
The ID of the deal
application/json
user_id
integer
required
The ID of the user
OK
/v1/deals/{id}/participants
Adds a participant to a deal.
id
integer
required
The ID of the deal
application/json
person_id
integer
required
The ID of the person
OK
/v1/deals/{id}/products
Adds a product to a deal, creating a new item called a deal-product.
id
integer
required
The ID of the deal
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_percentage
number
The discount %. If omitted, will be set to 0.
Default
0
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
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
OK
/v1/deals/{id}
Updates the properties of a deal. For more information, see the tutorial for updating a deal.
id
integer
required
The ID of the deal
application/json
title
string
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
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.
Value | Description |
---|---|
1 | Owner & followers |
3 | Entire company |
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
OK
/v1/deals/{id}/merge
Merges a deal with another deal. For more information, see the tutorial for merging two deals.
id
integer
required
The ID of the deal
application/json
merge_with_id
integer
required
The ID of the deal that the deal will be merged with
OK
/v1/deals/{id}/products/{product_attachment_id}
Updates the details of the product that has been attached to a deal.
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)
application/json
product_id
integer
required
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_percentage
number
The discount %. If omitted, will be set to 0.
Default
0
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
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
OK
/v1/deals
Marks multiple deals as deleted. After 30 days, the deals will be permanently deleted.
ids
string
required
The comma-separated IDs that will be deleted
OK
/v1/deals/{id}
Marks a deal as deleted. After 30 days, the deal will be permanently deleted.
id
integer
required
The ID of the deal
OK
/v1/deals/{id}/followers/{follower_id}
Deletes a follower from a deal.
id
integer
required
The ID of the deal
follower_id
integer
required
The ID of the follower
OK
/v1/deals/{id}/participants/{deal_participant_id}
Deletes a participant from a deal.
id
integer
required
The ID of the deal
deal_participant_id
integer
required
The ID of the participant of the deal
OK
/v1/deals/{id}/products/{product_attachment_id}
Deletes a product attachment from a deal, using the product_attachment_id
.
id
integer
required
The ID of the deal
product_attachment_id
integer
required
The product attachment ID
OK