Pipedrive API Reference and Documentation

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.

View quick guide: /v1 to /v2 migration

API v1

API v2

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

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

Response

200

Expand all

Copy code

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

Get all archived deals

Returns data about all archived deals.

View quick guide: /v1 to /v2 migration

API v1

API v2

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

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":{ ... }

Get all deals collection

Returns all deals. Please note that only global admins (those with global permissions) can access this endpoint. Users with regular permissions will receive a 403 response. Read more about global permissions here.
This endpoint has been deprecated. Please use GET /api/v2/deals instead.

Deprecated endpoint

Cost

Request

GET

/v1/deals/collection

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

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.

View quick guide: /v1 to /v2 migration

API v1

API v2

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.

API v1

Cost

Request

GET

/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

/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.

API v1

Cost

Request

GET

/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

/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":{ ... }

Get details of a deal

Returns the details of a specific deal.

View quick guide: /v1 to /v2 migration

API v1

API v2

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

custom_fields

string

Response

200

Expand all

Copy code

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

List activities associated with a deal

Lists activities associated with a deal.
This endpoint has been deprecated. Please use GET /api/v2/activities?deal_id={id} instead.

Deprecated endpoint

Cost

Request

GET

/v1/deals/{id}/activities

Path parameters

integer

required

The ID of the deal

Query parameters

start

integer

Pagination start

Default

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

exclude

string

A comma-separated string of activity IDs to exclude from result

Response

200

Expand all

Copy code

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

List updates about deal field values

Lists updates about field values of a deal.

API v1

Cost

Request

GET

/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":{ ... }

List files attached to a deal

Lists files associated with a deal.

API v1

Cost

Request

GET

/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.

API v1

Cost

Request

GET

/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 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.

API v1

Cost

Request

GET

/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 followers of a deal

Lists users who are following the deal.

View quick guide: /v1 to /v2 migration

API v1

API v2

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 mail messages associated with a deal

Lists mail messages associated with a deal.

API v1

Cost

Request

GET

/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.

API v1

Cost

Request

GET

/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 permitted users

Lists the users permitted to access a deal.

API v1

Cost

Request

GET

/v1/deals/{id}/permittedUsers

Path parameters

integer

required

The ID of the deal

Response

200

Expand all

Copy code

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

List all persons associated with a deal

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.
This endpoint has been deprecated. Please use GET /api/v2/persons?deal_id={id} instead.

Deprecated endpoint

Cost

Request

GET

/v1/deals/{id}/persons

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 products attached to a deal

Lists products attached to a deal.

View quick guide: /v1 to /v2 migration

API v1

API v2

Cost

Request

GET

/api/v2/deals/{id}/products

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

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

Values

add_time

update_time

sort_direction

string

The sorting direction. Supported values: asc, desc.

Default

asc

Values

asc

desc

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.

API v2

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":{ ... }

Get deal products of several deals

Returns data about products attached to deals

API v2

Cost

Request

GET

/api/v2/deals/products

Query parameters

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

Values

deal_id

add_time

update_time

sort_direction

string

The sorting direction. Supported values: asc, desc.

Default

asc

Values

asc

desc

Response

200

Expand all

Copy code

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

List discounts added to a deal

Lists discounts attached to a deal.

API v2

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 installments added to a list of deals

Lists installments attached to a list of deals.

Only available in Advanced and above plans.

API v2

Endpoint is in beta

Cost

Request

GET

/api/v2/deals/installments

Query parameters

deal_ids

array

required

An array of integers with the IDs of the deals for which the attached installments 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, billing_date, deal_id.

Default

Values

billing_date

deal_id

sort_direction

string

The sorting direction. Supported values: asc, desc.

Default

asc

Values

asc

desc

Response

200

Expand all

Copy code

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

Get Deal conversion status (BETA)

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.

API v2

Endpoint is in beta

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

Add a deal

Adds a new deal.

View quick guide: /v1 to /v2 migration

API v1

API v2

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

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

Response

200

Expand all

Copy code

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

Duplicate deal

Duplicates a deal.

API v1

Cost

Request

POST

/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

API v1

API v2

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.

API v1

Cost

Request

POST

/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":{ ... }

Add a product to a deal

Adds a product to a deal, creating a new item called a deal-product.

View quick guide: /v1 to /v2 migration

API v1

API v2

Cost

Request

POST

/api/v2/deals/{id}/products

Path parameters

integer

required

The ID of the deal

Body parameters

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

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

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

When billing_frequency is set to weekly, this field cannot 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 208

billing_start_date

string

Only available in Advanced and above plans

The billing start date. Must be between 10 years in the past and 10 years in the future

Format

YYYY-MM-DD

Response

201

Created

Expand all

Copy code

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

Add a discount to a deal

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

API v2

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":{ ... }

Add an installment to a deal

Adds an installment to a deal.

An installment can only be added if the deal includes at least one one-time product. If the deal contains at least one recurring product, adding installments is not allowed.

Only available in Advanced and above plans.

API v2

Endpoint is in beta

Cost

Request

POST

/api/v2/deals/{id}/installments

Path parameters

integer

required

The ID of the deal

Body parameters

application/json

description

string

required

The name of the installment.

amount

number

required

The installment amount. Must be a positive number (excluding 0).

billing_date

string

required

The date which the installment will be charged. Must be in the format YYYY-MM-DD.

Response

200

Expand all

Copy code

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

Convert a deal to a lead (BETA)

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.

API v2

Endpoint is in beta

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

Update a deal

Updates the properties of a deal.

View quick guide: /v1 to /v2 migration

API v1

API v2

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

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

Response

200

Expand all

Copy code

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

Merge two deals

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

API v1

Cost

Request

PUT

/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 the product attached to a deal

Updates the details of the product that has been attached to a deal.

View quick guide: /v1 to /v2 migration

API v1

API v2

Cost

Request

PATCH

/api/v2/deals/{id}/products/{product_attachment_id}

Path parameters

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

item_price

number

The price value of the product

quantity

number

The quantity of the product

tax

number

The product tax

Default

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

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

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

When billing_frequency is set to weekly, this field cannot 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 208

billing_start_date

string

Only available in Advanced and above plans

The billing start date. Must be between 10 years in the past and 10 years in the future

Format

YYYY-MM-DD

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.

API v2

Cost

Request

PATCH

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

Path parameters

integer

required

The ID of the deal

discount_id

integer

required

The ID of the discount

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":{ ... }

Update an installment added to a deal

Edits an installment added to a deal.

Only available in Advanced and above plans.

API v2

Endpoint is in beta

Cost

Request

PATCH

/api/v2/deals/{id}/installments/{installment_id}

Path parameters

integer

required

The ID of the deal

installment_id

integer

required

The ID of the installment

Body parameters

application/json

description

string

The name of the installment.

amount

number

The installment amount. Must be a positive number (excluding 0).

billing_date

string

The date which the installment will be charged. Must be in the format YYYY-MM-DD.

Response

200

Expand all

Copy code

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

Delete multiple deals in bulk

Marks multiple deals as deleted. After 30 days, the deals will be permanently deleted.
This endpoint has been deprecated. Please use DELETE /api/v2/deals/{id} instead.

Deprecated endpoint

Cost

Request

DELETE

/v1/deals

Query parameters

ids

string

required

The comma-separated IDs that will be deleted

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.

View quick guide: /v1 to /v2 migration

API v1

API v2

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 follower from a deal

Deletes a user follower from the deal.

View quick guide: /v1 to /v2 migration

API v1

API v2

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.

API v1

Cost

Request

DELETE

/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":{ ... }

Delete an attached product from a deal

Deletes a product attachment from a deal, using the product_attachment_id.

View quick guide: /v1 to /v2 migration

API v1

API v2

Cost

Request

DELETE

/api/v2/deals/{id}/products/{product_attachment_id}

Path parameters

integer

required

The ID of the deal

product_attachment_id

integer

required

The product attachment ID

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.

API v2

Cost

Request

DELETE

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

Path parameters

integer

required

The ID of the deal

discount_id

integer

required

The ID of the discount

Response

200

Expand all

Copy code

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

Delete an installment from a deal

Removes an installment from a deal.

Only available in Advanced and above plans.

API v2

Endpoint is in beta

Cost

Request

DELETE

/api/v2/deals/{id}/installments/{installment_id}

Path parameters

integer

required

The ID of the deal

installment_id

integer

required

The ID of the installment

Response

200

Expand all

Copy code

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