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
.
Returns all deals. For more information, see the tutorial for getting all deals.
/api/v2/deals
filter_id
integer
If supplied, only deals matching the specified filter are returned
owner_id
integer
If supplied, only deals owned by the specified user are returned. If filter_id is provided, this is ignored.
person_id
integer
If supplied, only deals linked to the specified person are returned. If filter_id is provided, this is ignored.
org_id
integer
If supplied, only deals linked to the specified organization are returned. If filter_id is provided, this is ignored.
pipeline_id
integer
If supplied, only deals in the specified pipeline are returned. If filter_id is provided, this is ignored.
stage_id
integer
If supplied, only deals in the specified stage are returned. If filter_id is provided, this is ignored.
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. Multiple statuses can be included as a comma separated array. If filter_id is provided, this is ignored.
Values
open
won
lost
deleted
updated_since
string
If set, only deals with an update_time
later than or equal to this time are returned. In RFC3339 format, e.g. 2025-01-01T10:20:00Z.
updated_until
string
If set, only deals with an update_time
earlier than this time are returned. In RFC3339 format, e.g. 2025-01-01T10:20:00Z.
sort_by
string
The field to sort by. Supported fields: id
, update_time
, add_time
.
Default
id
Values
id
update_time
add_time
sort_direction
string
The sorting direction. Supported values: asc
, desc
.
Default
asc
Values
asc
desc
include_fields
string
Optional comma separated string array of additional fields to include
Values
next_activity_id
last_activity_id
first_won_time
products_count
files_count
notes_count
followers_count
email_messages_count
activities_count
done_activities_count
undone_activities_count
participants_count
last_incoming_mail_time
last_outgoing_mail_time
custom_fields
string
Optional comma separated string array of custom fields keys to include. If you are only interested in a particular set of custom fields, please use this parameter for faster results and smaller response.
A maximum of 15 keys is allowed.
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.
cursor
string
For pagination, the marker (an opaque string value) representing the first item on the next page
OK
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.
/v1/deals/collection
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
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.
/api/v2/deals/search
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
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.
cursor
string
For pagination, the marker (an opaque string value) representing the first item on the next page
OK
Returns a summary of all the deals.
/v1/deals/summary
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
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
.
/v1/deals/timeline
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
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.
/api/v2/deals/{id}
id
integer
required
The ID of the deal
include_fields
string
Optional comma separated string array of additional fields to include
Values
next_activity_id
last_activity_id
first_won_time
products_count
files_count
notes_count
followers_count
email_messages_count
activities_count
done_activities_count
undone_activities_count
participants_count
last_incoming_mail_time
last_outgoing_mail_time
custom_fields
string
Optional comma separated string array of custom fields keys to include. If you are only interested in a particular set of custom fields, please use this parameter for faster results and smaller response.
A maximum of 15 keys is allowed.
OK
Lists activities associated with a deal.
/v1/deals/{id}/activities
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
Lists updates about field values of a deal.
/v1/deals/{id}/changelog
id
integer
required
The ID of the deal
cursor
string
For pagination, the marker (an opaque string value) representing the first item on the next page
limit
integer
Items shown per page
OK
Lists files associated with a deal.
/v1/deals/{id}/files
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
Lists updates about a deal.
/v1/deals/{id}/flow
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
List updates about participants of a deal. This is a cursor-paginated endpoint. For more information, please refer to our documentation on pagination.
/v1/deals/{id}/participantsChangelog
id
integer
required
The ID of the deal
limit
integer
Items shown per page
cursor
string
For pagination, the marker (an opaque string value) representing the first item on the next page
OK
Lists the followers of a deal.
/v1/deals/{id}/followers
id
integer
required
The ID of the deal
OK
Lists mail messages associated with a deal.
/v1/deals/{id}/mailMessages
id
integer
required
The ID of the deal
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
OK
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.
/v1/deals/{id}/participants
id
integer
required
The ID of the deal
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
OK
Lists the users permitted to access a deal.
/v1/deals/{id}/permittedUsers
id
integer
required
The ID of the deal
OK
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.
/v1/deals/{id}/persons
id
integer
required
The ID of the deal
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
OK
Lists products attached to a deal.
/api/v2/deals/{id}/products
id
integer
required
The ID of the deal
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.
sort_by
string
The field to sort by. Supported fields: id
, add_time
, update_time
.
Default
id
Values
id
add_time
update_time
sort_direction
string
The sorting direction. Supported values: asc
, desc
.
Default
asc
Values
asc
desc
OK
Returns data about products attached to deals
/api/v2/deals/products
deal_ids
array
required
An array of integers with the IDs of the deals for which the attached products will be returned. A maximum of 100 deal IDs can be provided.
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.
sort_by
string
The field to sort by. Supported fields: id
, deal_id
, add_time
, update_time
.
Default
id
Values
id
deal_id
add_time
update_time
sort_direction
string
The sorting direction. Supported values: asc
, desc
.
Default
asc
Values
asc
desc
OK
Lists discounts attached to a deal.
/api/v2/deals/{id}/discounts
id
integer
required
The ID of the deal
OK
Adds a new deal. All deals created through the Pipedrive API will have a origin
set to API
. 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.
/api/v2/deals
application/json
title
string
required
The title of the deal
owner_id
integer
The ID of the user who owns the deal
person_id
integer
The ID of the person linked to the deal
org_id
integer
The ID of the organization linked to the deal
pipeline_id
integer
The ID of the pipeline associated with the deal
stage_id
integer
The ID of the deal stage
value
number
The value of the deal
currency
string
The currency associated with the deal
add_time
string
The creation date and time of the deal
update_time
string
The last updated date and time of the deal
stage_change_time
string
The last updated date and time of the deal stage
is_deleted
boolean
Whether the deal is deleted or not
status
string
The status of the deal
probability
number
The success probability percentage of the deal
lost_reason
string
The reason for losing the deal. Can only be set if deal status is lost.
visible_to
integer
The visibility of the deal
close_time
string
The date and time of closing the deal. Can only be set if deal status is won or lost.
won_time
string
The date and time of changing the deal status as won. Can only be set if deal status is won.
lost_time
string
The date and time of changing the deal status as lost. Can only be set if deal status is lost.
expected_close_date
string
The expected close date of the deal
Format
date
label_ids
array
The IDs of labels assigned to the deal
OK
Duplicates a deal.
/v1/deals/{id}/duplicate
id
integer
required
The ID of the deal
OK
Adds a follower to a deal.
/v1/deals/{id}/followers
id
integer
required
The ID of the deal
application/json
user_id
integer
required
The ID of the user
OK
Adds a participant to a deal.
/v1/deals/{id}/participants
id
integer
required
The ID of the deal
application/json
person_id
integer
required
The ID of the person
OK
Adds a product to a deal, creating a new item called a deal-product.
/api/v2/deals/{id}/products
id
integer
required
The ID of the deal
application/json
product_id
integer
required
The ID of the product
item_price
number
required
The price value of the product
quantity
number
required
The quantity of the product
tax
number
The product tax
Default
0
comments
string
The comments of the product
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
is_enabled
boolean
Whether this product is enabled for the deal
Not possible to disable the product if the deal has installments associated and the product is the last one enabled
Not possible to enable the product if the deal has installments associated and the product is recurring
Default
true
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
discount_type
string
The value of the discount. The discount_type
field can be used to specify whether the value is an amount or a percentage
Default
percentage
Values
percentage
amount
product_variation_id
integer
The ID of the product variation
billing_frequency
string
Only available in Advanced and above plans
How often a customer is billed for access to a service or product
To set billing_frequency
different than one-time
, the deal must not have installments associated
A deal can have up to 20 products attached with billing_frequency
different than one-time
Default
one-time
Values
one-time
annually
semi-annually
quarterly
monthly
weekly
billing_frequency_cycles
integer
Only available in Advanced and above plans
The number of times the billing frequency repeats for a product in a deal
When billing_frequency
is set to one-time
, this field must be null
For all the other values of billing_frequency
, null
represents a product billed indefinitely
Must be a positive integer less or equal to 312
billing_start_date
string
Only available in Advanced and above plans
The billing start date. Must be between 15 years in the past and 15 years in the future
Format
YYYY-MM-DD
Created
Adds a discount to a deal changing, the deal value if the deal has one-time products attached.
/api/v2/deals/{id}/discounts
id
integer
required
The ID of the deal
application/json
description
string
required
The name of the discount.
amount
number
required
The discount amount. Must be a positive number (excluding 0).
type
string
required
Determines whether the discount is applied as a percentage or a fixed amount.
Values
percentage
amount
Created
Updates the properties of a deal. For more information, see the tutorial for updating a deal.
/api/v2/deals/{id}
id
integer
required
The ID of the deal
application/json
title
string
The title of the deal
owner_id
integer
The ID of the user who owns the deal
person_id
integer
The ID of the person linked to the deal
org_id
integer
The ID of the organization linked to the deal
pipeline_id
integer
The ID of the pipeline associated with the deal
stage_id
integer
The ID of the deal stage
value
number
The value of the deal
currency
string
The currency associated with the deal
add_time
string
The creation date and time of the deal
update_time
string
The last updated date and time of the deal
stage_change_time
string
The last updated date and time of the deal stage
is_deleted
boolean
Whether the deal is deleted or not
status
string
The status of the deal
probability
number
The success probability percentage of the deal
lost_reason
string
The reason for losing the deal. Can only be set if deal status is lost.
visible_to
integer
The visibility of the deal
close_time
string
The date and time of closing the deal. Can only be set if deal status is won or lost.
won_time
string
The date and time of changing the deal status as won. Can only be set if deal status is won.
lost_time
string
The date and time of changing the deal status as lost. Can only be set if deal status is lost.
expected_close_date
string
The expected close date of the deal
Format
date
label_ids
array
The IDs of labels assigned to the deal
OK
Merges a deal with another deal. For more information, see the tutorial for merging two deals.
/v1/deals/{id}/merge
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
Updates the details of the product that has been attached to a deal.
/api/v2/deals/{id}/products/{product_attachment_id}
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
The ID of the product
item_price
number
The price value of the product
quantity
number
The quantity of the product
tax
number
The product tax
Default
0
comments
string
The comments of the product
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
is_enabled
boolean
Whether this product is enabled for the deal
Not possible to disable the product if the deal has installments associated and the product is the last one enabled
Not possible to enable the product if the deal has installments associated and the product is recurring
Default
true
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
discount_type
string
The value of the discount. The discount_type
field can be used to specify whether the value is an amount or a percentage
Default
percentage
Values
percentage
amount
product_variation_id
integer
The ID of the product variation
billing_frequency
string
Only available in Advanced and above plans
How often a customer is billed for access to a service or product
To set billing_frequency
different than one-time
, the deal must not have installments associated
A deal can have up to 20 products attached with billing_frequency
different than one-time
Values
one-time
annually
semi-annually
quarterly
monthly
weekly
billing_frequency_cycles
integer
Only available in Advanced and above plans
The number of times the billing frequency repeats for a product in a deal
When billing_frequency
is set to one-time
, this field must be null
For all the other values of billing_frequency
, null
represents a product billed indefinitely
Must be a positive integer less or equal to 312
billing_start_date
string
Only available in Advanced and above plans
The billing start date. Must be between 15 years in the past and 15 years in the future
Format
YYYY-MM-DD
OK
Edits a discount added to a deal, changing the deal value if the deal has one-time products attached.
/api/v2/deals/{id}/discounts/{discount_id}
id
integer
required
The ID of the deal
discount_id
integer
required
The ID of the discount
application/json
description
string
The name of the discount.
amount
number
The discount amount. Must be a positive number (excluding 0).
type
string
Determines whether the discount is applied as a percentage or a fixed amount.
Values
percentage
amount
OK
Marks multiple deals as deleted. After 30 days, the deals will be permanently deleted.
/v1/deals
ids
string
required
The comma-separated IDs that will be deleted
OK
Marks a deal as deleted. After 30 days, the deal will be permanently deleted.
/api/v2/deals/{id}
id
integer
required
The ID of the deal
OK
Deletes a follower from a deal.
/v1/deals/{id}/followers/{follower_id}
id
integer
required
The ID of the deal
follower_id
integer
required
The ID of the follower
OK
Deletes a participant from a deal.
/v1/deals/{id}/participants/{deal_participant_id}
id
integer
required
The ID of the deal
deal_participant_id
integer
required
The ID of the participant of the deal
OK
Deletes a product attachment from a deal, using the product_attachment_id
Not possible to delete the attached product if the deal has installments associated and the product is the last one enabled
/api/v2/deals/{id}/products/{product_attachment_id}
id
integer
required
The ID of the deal
product_attachment_id
integer
required
The product attachment ID
OK
Removes a discount from a deal, changing the deal value if the deal has one-time products attached.
/api/v2/deals/{id}/discounts/{discount_id}
id
integer
required
The ID of the deal
discount_id
integer
required
The ID of the discount
OK