Pipedrive API v1–v2 Dev References (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

Returns data about all not archived deals.

Cost

Request

GET

/api/v2/deals

Query parameters

filter_id

integer

If supplied, only deals matching the specified filter are returned

ids

string

Optional comma separated string array of up to 100 entity ids to fetch. If filter_id is provided, this is ignored. If any of the requested entities do not exist or are not visible, they are not included in the response.

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

Values

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

smart_bcc_email

source_lead_id

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.

include_option_labels

boolean

When provided with a 'true' value, single option and multiple option custom fields values contain objects in the form of '{ id: number, label: string }' instead of plain id

include_labels

boolean

When provided with 'true' value, response will include an array of label objects in the form of '{ id: number, label: string }'

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

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":[ ... ]
- ▶
  "additional_data":{ ... }

Get details of a deal

Returns the details of a specific deal.

Cost

Request

GET

/api/v2/deals/{id}

Path parameters

integer

required

The ID of the deal

Query parameters

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

smart_bcc_email

source_lead_id

custom_fields

string

include_option_labels

boolean

When provided with a 'true' value, single option and multiple option custom fields values contain objects in the form of '{ id: number, label: string }' instead of plain id

include_labels

boolean

When provided with 'true' value, response will include an array of label objects in the form of '{ id: number, label: string }'

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }

List updates about deal field values

Lists updates about field values of a deal.

Cost

Request

GET

/api/v1/deals/{id}/changelog

Path parameters

integer

required

The ID of the deal

Query parameters

cursor

string

For pagination, the marker (an opaque string value) representing the first item on the next page

limit

integer

Items shown per page

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":[ ... ]
- ▶
  "additional_data":{ ... }

Get Deal conversion status

Returns information about the conversion. Status is always present and its value (not_started, running, completed, failed, rejected) represents the current state of the conversion. Lead ID is only present if the conversion was successfully finished. This data is only temporary and removed after a few days.

Cost

Request

GET

/api/v2/deals/{id}/convert/status/{conversion_id}

Path parameters

integer

required

The ID of a deal

conversion_id

string

required

The ID of the conversion

Format

uuid

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }
- "additional_data":null

List discounts added to a deal

Lists discounts attached to a deal.

Cost

Request

GET

/api/v2/deals/{id}/discounts

Path parameters

integer

required

The ID of the deal

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":[ ... ]

List files attached to a deal

Lists files associated with a deal.

Cost

Request

GET

/api/v1/deals/{id}/files

Path parameters

integer

required

The ID of the deal

Query parameters

start

integer

Pagination start

Default

limit

integer

Items shown per page. Please note that a maximum value of 100 is allowed.

sort

string

Supported fields: id, update_time

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":[ ... ]
- ▶
  "additional_data":{ ... }

List updates about a deal

Lists updates about a deal.

Cost

Request

GET

/api/v1/deals/{id}/flow

Path parameters

integer

required

The ID of the deal

Query parameters

start

integer

Pagination start

Default

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

200

Expand all

Copy code

- "success":true
- ▶
  "data":[ ... ]
- ▶
  "additional_data":{ ... }
- ▶
  "related_objects":{ ... }

List followers of a deal

Lists users who are following the deal.

View quick guide: /v1 to /v2 migration

Cost

Request

GET

/api/v2/deals/{id}/followers

Path parameters

integer

required

The ID of the deal

Query parameters

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

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":[ ... ]
- ▶
  "additional_data":{ ... }

List followers changelog of a deal

Lists changelogs about users have followed the deal.

Cost

Request

GET

/api/v2/deals/{id}/followers/changelog

Path parameters

integer

required

The ID of the deal

Query parameters

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

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":[ ... ]
- ▶
  "additional_data":{ ... }

List mail messages associated with a deal

Lists mail messages associated with a deal.

Cost

Request

GET

/api/v1/deals/{id}/mailMessages

Path parameters

integer

required

The ID of the deal

Query parameters

start

integer

Pagination start

Default

limit

integer

Items shown per page

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":[ ... ]
- ▶
  "additional_data":{ ... }

List participants of a deal

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.

Cost

Request

GET

/api/v1/deals/{id}/participants

Path parameters

integer

required

The ID of the deal

Query parameters

start

integer

Pagination start

Default

limit

integer

Items shown per page

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":[ ... ]
- ▶
  "additional_data":{ ... }
- ▶
  "related_objects":{ ... }

List updates about participants of a deal

List updates about participants of a deal. This is a cursor-paginated endpoint. For more information, please refer to our documentation on pagination.

Cost

Request

GET

/api/v1/deals/{id}/participantsChangelog

Path parameters

integer

required

The ID of the deal

Query parameters

limit

integer

Items shown per page

cursor

string

For pagination, the marker (an opaque string value) representing the first item on the next page

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":[ ... ]
- ▶
  "additional_data":{ ... }

List permitted users

Lists the users permitted to access a deal.

Cost

Request

GET

/api/v1/deals/{id}/permittedUsers

Path parameters

integer

required

The ID of the deal

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":[ ... ]

Get all archived deals

Returns data about all archived deals.

View quick guide: /v1 to /v2 migration

Cost

Request

GET

/api/v2/deals/archived

Query parameters

filter_id

integer

If supplied, only deals matching the specified filter are returned

ids

string

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

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

Values

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

smart_bcc_email

source_lead_id

custom_fields

string

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

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":[ ... ]
- ▶
  "additional_data":{ ... }

Search deals

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.

Cost

Request

GET

/api/v2/deals/search

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

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

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }
- ▶
  "additional_data":{ ... }

Get deals summary

Returns a summary of all not archived deals.

Cost

Request

GET

/api/v1/deals/summary

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.

pipeline_id

integer

Only deals within the given pipeline will be returned

stage_id

integer

Only deals within the given stage will be returned

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }

Get archived deals summary

Returns a summary of all archived deals.

Deprecated endpoint

Cost

Request

GET

/api/v1/deals/summary/archived

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.

pipeline_id

integer

Only deals within the given pipeline will be returned

stage_id

integer

Only deals within the given stage will be returned

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }

Get deals timeline

Returns not archived 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.

Cost

Request

GET

/api/v1/deals/timeline

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

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

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }

Get archived deals timeline

Returns archived 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.

Deprecated endpoint

Cost

Request

GET

/api/v1/deals/timeline/archived

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

totals_convert_currency

string

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }

Add a new deal

Adds a new deal.

Cost

Request

POST

/api/v2/deals

Body parameters

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

is_deleted

boolean

Whether the deal is deleted or not

is_archived

boolean

Whether the deal is archived or not

archive_time

string

The optional date and time of archiving the deal in UTC. Format: YYYY-MM-DD HH:MM:SS. If omitted and is_archived is true, it will be set to the current date and time.

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

custom_fields

object

An object where each key represents a custom field. All custom fields are referenced as randomly generated 40-character hashes. To clear a custom field value, set it to null. For multi-option fields (field type set), use null to clear the selection — sending an empty array [] is not supported and will result in a validation error.

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }

Convert a deal to a lead

Initiates a conversion of a deal to a lead. The return value is an ID of a job that was assigned to perform the conversion. Related entities (notes, files, emails, activities, ...) are transferred during the process to the target entity. There are exceptions for entities like invoices or history that are not transferred and remain linked to the original deal. If the conversion is successful, the deal is marked as deleted. To retrieve the created entity ID and the result of the conversion, call the /api/v2/deals/{deal_id}/convert/status/{conversion_id} endpoint.

Cost

Request

POST

/api/v2/deals/{id}/convert/lead

Path parameters

integer

required

The ID of the deal to convert

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }
- "additional_data":null

Add a discount to a deal

Adds a discount to a deal, changing the deal value if the deal has one-time products attached.

Cost

Request

POST

/api/v2/deals/{id}/discounts

Path parameters

integer

required

The ID of the deal

Body parameters

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

Response

201

Created

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }

Duplicate deal

Duplicates a deal.

Cost

Request

POST

/api/v1/deals/{id}/duplicate

Path parameters

integer

required

The ID of the deal

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }

Add a follower to a deal

Adds a user as a follower to the deal.

View quick guide: /v1 to /v2 migration

Cost

Request

POST

/api/v2/deals/{id}/followers

Path parameters

integer

required

The ID of the deal

Body parameters

application/json

user_id

integer

required

The ID of the user to add as a follower

Response

201

Created

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }

Add a participant to a deal

Adds a participant to a deal.

Cost

Request

POST

/api/v1/deals/{id}/participants

Path parameters

integer

required

The ID of the deal

Body parameters

application/json

person_id

integer

required

The ID of the person

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }
- ▶
  "related_objects":{ ... }

Merge two deals

Merges a deal with another deal. For more information, see the tutorial for merging two deals.

Cost

Request

PUT

/api/v1/deals/{id}/merge

Path parameters

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

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }

Update a deal

Updates the properties of a deal.

Cost

Request

PATCH

/api/v2/deals/{id}

Path parameters

integer

required

The ID of the deal

Body parameters

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

is_deleted

boolean

Whether the deal is deleted or not

is_archived

boolean

Whether the deal is archived or not

archive_time

string

The optional date and time of archiving the deal in UTC. Format: YYYY-MM-DD HH:MM:SS. If omitted and is_archived is true, it will be set to the current date and time.

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

custom_fields

object

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }

Update a discount added to a deal

Edits a discount added to a deal, changing the deal value if the deal has one-time products attached.

Cost

Request

PATCH

/api/v2/deals/{id}/discounts/{discount_id}

Path parameters

integer

required

The ID of the deal

discount_id

string

required

The ID of the discount

Format

uuid

Body parameters

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

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }

Delete a deal

Marks a deal as deleted. After 30 days, the deal will be permanently deleted.

Cost

Request

DELETE

/api/v2/deals/{id}

Path parameters

integer

required

The ID of the deal

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }

Delete a discount from a deal

Removes a discount from a deal, changing the deal value if the deal has one-time products attached.

Cost

Request

DELETE

/api/v2/deals/{id}/discounts/{discount_id}

Path parameters

integer

required

The ID of the deal

discount_id

string

required

The ID of the discount

Format

uuid

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }

Delete a follower from a deal

Deletes a user follower from the deal.

View quick guide: /v1 to /v2 migration

Cost

Request

DELETE

/api/v2/deals/{id}/followers/{follower_id}

Path parameters

integer

required

The ID of the deal

follower_id

integer

required

The ID of the following user

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }

Delete a participant from a deal

Deletes a participant from a deal.

Cost

Request

DELETE

/api/v1/deals/{id}/participants/{deal_participant_id}

Path parameters

integer

required

The ID of the deal

deal_participant_id

integer

required

The ID of the participant of the deal

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }