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

Copy link
Copy to clipboard
GET

/v1/deals

Returns all deals. For more information, see the tutorial for getting all deals.

Query parameters

user_id

integer

If supplied, only deals matching the given user will be returned. However, filter_id and owned_by_you takes precedence over user_id when supplied.

filter_id

integer

The ID of the filter to use

stage_id

integer

If supplied, only deals within the given stage will be returned

status

string

Only fetch deals with a specific status. If omitted, all not deleted deals are returned. If set to deleted, deals that have been deleted up to 30 days ago will be included.

Default

all_not_deleted

Values

open

won

lost

deleted

all_not_deleted

start

integer

Pagination start

Default

0

limit

integer

Items shown per page

sort

string

The field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys).

owned_by_you

number

When supplied, only deals owned by you are returned. However, filter_id takes precedence over owned_by_you when both are supplied.

Values

0

1

Response
200

OK

Expand all
Copy code
    • true
    • [ ... ]
      • { ... }
        • { ... }

        Get all deals (BETA)

        Copy link
        Copy to clipboard
        GET

        /v1/deals/collection

        Returns all deals. This is a cursor-paginated endpoint that is currently in BETA. For more information, please refer to our documentation on pagination. Please note that only global admins (those with global permissions) can access these endpoints. Users with regular permissions will receive a 403 response. Read more about global permissions here.

        Query parameters

        cursor

        string

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

        limit

        integer

        For pagination, the limit of entries to be returned. If not provided, 100 items will be returned. Please note that a maximum value of 500 is allowed.

        since

        string

        The time boundary that points to the start of the range of data. Datetime in ISO 8601 format. E.g. 2022-11-01 08:55:59. Operates on the update_time field.

        until

        string

        The time boundary that points to the end of the range of data. Datetime in ISO 8601 format. E.g. 2022-11-01 08:55:59. Operates on the update_time field.

        user_id

        integer

        If supplied, only deals matching the given user will be returned

        stage_id

        integer

        If supplied, only deals within the given stage will be returned

        status

        string

        Only fetch deals with a specific status. If omitted, all not deleted deals are returned. If set to deleted, deals that have been deleted up to 30 days ago will be included.

        Values

        open

        won

        lost

        deleted

        Response
        200

        OK

        Expand all
        Copy code
          • true
          • [ ... ]
            • { ... }

            Search deals

            Copy link
            Copy to clipboard
            GET

            /v1/deals/search

            Searches all deals by title, notes and/or custom fields. This endpoint is a wrapper of /v1/itemSearch with a narrower OAuth scope. Found deals can be filtered by the person ID and the organization ID.

            Query parameters

            term

            string

            required

            The search term to look for. Minimum 2 characters (or 1 if using exact_match). Please note that the search term has to be URL encoded.

            fields

            string

            A comma-separated string array. The fields to perform the search from. Defaults to all of them.

            Values

            custom_fields

            notes

            title

            exact_match

            boolean

            When enabled, only full exact matches against the given term are returned. It is not case sensitive.

            Values

            true

            false

            person_id

            integer

            Will filter deals by the provided person ID. The upper limit of found deals associated with the person is 2000.

            organization_id

            integer

            Will filter deals by the provided organization ID. The upper limit of found deals associated with the organization is 2000.

            status

            string

            Will filter deals by the provided specific status. open = Open, won = Won, lost = Lost. The upper limit of found deals associated with the status is 2000.

            Values

            open

            won

            lost

            include_fields

            string

            Supports including optional fields in the results which are not provided by default

            Values

            deal.cc_email

            start

            integer

            Pagination start. Note that the pagination is based on main results and does not include related items when using search_for_related_items parameter.

            Default

            0

            limit

            integer

            Items shown per page

            Response
            200

            OK

            Expand all
            Copy code
              • true
              • { ... }
                • { ... }

                Get deals summary

                Copy link
                Copy to clipboard
                GET

                /v1/deals/summary

                Returns a summary of all the deals.

                Query parameters

                status

                string

                Only fetch deals with a specific status. open = Open, won = Won, lost = Lost

                Values

                open

                won

                lost

                filter_id

                integer

                user_id will not be considered. Only deals matching the given filter will be returned.

                user_id

                integer

                Only deals matching the given user will be returned. user_id will not be considered if you use filter_id.

                stage_id

                integer

                Only deals within the given stage will be returned

                Response
                200

                OK

                Expand all
                Copy code
                  • true
                  • { ... }

                  Get deals timeline

                  Copy link
                  Copy to clipboard
                  GET

                  /v1/deals/timeline

                  Returns open and won deals, grouped by a defined interval of time set in a date-type dealField (field_key) — e.g. when month is the chosen interval, and 3 months are asked starting from January 1st, 2012, deals are returned grouped into 3 groups — January, February and March — based on the value of the given field_key.

                  Query parameters

                  start_date

                  string

                  required

                  The date when the first interval starts. Format: YYYY-MM-DD

                  Format

                  date

                  interval

                  string

                  required

                  The type of the interval

                  ValueDescription
                  dayDay
                  weekA full week (7 days) starting from start_date
                  monthA full month (depending on the number of days in given month) starting from start_date
                  quarterA full quarter (3 months) starting from start_date

                  Values

                  day

                  week

                  month

                  quarter

                  amount

                  integer

                  required

                  The number of given intervals, starting from start_date, to fetch. E.g. 3 (months).

                  field_key

                  string

                  required

                  The date field key which deals will be retrieved from

                  user_id

                  integer

                  If supplied, only deals matching the given user will be returned

                  pipeline_id

                  integer

                  If supplied, only deals matching the given pipeline will be returned

                  filter_id

                  integer

                  If supplied, only deals matching the given filter will be returned

                  exclude_deals

                  number

                  Whether to exclude deals list (1) or not (0). Note that when deals are excluded, the timeline summary (counts and values) is still returned.

                  Values

                  0

                  1

                  totals_convert_currency

                  string

                  The 3-letter currency code of any of the supported currencies. When supplied, totals_converted is returned per each interval which contains the currency-converted total amounts in the given currency. You may also set this parameter to default_currency in which case the user's default currency is used.

                  Response
                  200

                  OK

                  Expand all
                  Copy code
                    • true
                    • { ... }

                    Get details of a deal

                    Copy link
                    Copy to clipboard
                    GET

                    /v1/deals/{id}

                    Returns the details of a specific deal. Note that this also returns some additional fields which are not present when asking for all deals – such as deal age and stay in pipeline stages. Also note that custom fields appear as long hashes in the resulting data. These hashes can be mapped against the key value of dealFields. For more information, see the tutorial for getting details of a deal.

                    Path parameters

                    id

                    integer

                    required

                    The ID of the deal

                    Response
                    200

                    OK

                    Expand all
                    Copy code
                      • true
                      • { ... }
                        • { ... }
                          • { ... }

                          List activities associated with a deal

                          Copy link
                          Copy to clipboard
                          GET

                          /v1/deals/{id}/activities

                          Lists activities associated with a deal.

                          Path parameters

                          id

                          integer

                          required

                          The ID of the deal

                          Query parameters

                          start

                          integer

                          Pagination start

                          Default

                          0

                          limit

                          integer

                          Items shown per page

                          done

                          number

                          Whether the activity is done or not. 0 = Not done, 1 = Done. If omitted, returns both Done and Not done activities.

                          Values

                          0

                          1

                          exclude

                          string

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

                          Response
                          200

                          OK

                          Expand all
                          Copy code
                            • true
                            • [ ... ]
                              • { ... }
                                • { ... }

                                List files attached to a deal

                                Copy link
                                Copy to clipboard
                                GET

                                /v1/deals/{id}/files

                                Lists files associated with a deal.

                                Path parameters

                                id

                                integer

                                required

                                The ID of the deal

                                Query parameters

                                start

                                integer

                                Pagination start

                                Default

                                0

                                limit

                                integer

                                Items shown per page

                                sort

                                string

                                The field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys). Supported fields: id, user_id, deal_id, person_id, org_id, product_id, add_time, update_time, file_name, file_type, file_size, comment.

                                Response
                                200

                                OK

                                Expand all
                                Copy code
                                  • true
                                  • [ ... ]
                                    • { ... }

                                    List updates about a deal

                                    Copy link
                                    Copy to clipboard
                                    GET

                                    /v1/deals/{id}/flow

                                    Lists updates about a deal.

                                    Path parameters

                                    id

                                    integer

                                    required

                                    The ID of the deal

                                    Query parameters

                                    start

                                    integer

                                    Pagination start

                                    Default

                                    0

                                    limit

                                    integer

                                    Items shown per page

                                    all_changes

                                    string

                                    Whether to show custom field updates or not. 1 = Include custom field changes. If omitted returns changes without custom field updates.

                                    items

                                    string

                                    A comma-separated string for filtering out item specific updates. (Possible values - call, activity, plannedActivity, change, note, deal, file, dealChange, personChange, organizationChange, follower, dealFollower, personFollower, organizationFollower, participant, comment, mailMessage, mailMessageWithAttachment, invoice, document, marketing_campaign_stat, marketing_status_change)

                                    Response
                                    200

                                    OK

                                    Expand all
                                    Copy code
                                      • true
                                      • [ ... ]
                                        • { ... }
                                          • { ... }

                                          List followers of a deal

                                          Copy link
                                          Copy to clipboard
                                          GET

                                          /v1/deals/{id}/followers

                                          Lists the followers of a deal.

                                          Path parameters

                                          id

                                          integer

                                          required

                                          The ID of the deal

                                          Response
                                          200

                                          OK

                                          Expand all
                                          Copy code
                                            • true
                                            • [ ... ]
                                              • { ... }

                                              List mail messages associated with a deal

                                              Copy link
                                              Copy to clipboard
                                              GET

                                              /v1/deals/{id}/mailMessages

                                              Lists mail messages associated with a deal.

                                              Path parameters

                                              id

                                              integer

                                              required

                                              The ID of the deal

                                              Query parameters

                                              start

                                              integer

                                              Pagination start

                                              Default

                                              0

                                              limit

                                              integer

                                              Items shown per page

                                              Response
                                              200

                                              OK

                                              Expand all
                                              Copy code
                                                • true
                                                • [ ... ]
                                                  • { ... }

                                                  List participants of a deal

                                                  Copy link
                                                  Copy to clipboard
                                                  GET

                                                  /v1/deals/{id}/participants

                                                  Lists the participants associated with a deal.
                                                  If a company uses the Campaigns product, then this endpoint will also return the data.marketing_status field.

                                                  Path parameters

                                                  id

                                                  integer

                                                  required

                                                  The ID of the deal

                                                  Query parameters

                                                  start

                                                  integer

                                                  Pagination start

                                                  Default

                                                  0

                                                  limit

                                                  integer

                                                  Items shown per page

                                                  Response
                                                  200

                                                  OK

                                                  Expand all
                                                  Copy code
                                                    • true
                                                    • [ ... ]
                                                      • { ... }
                                                        • { ... }

                                                        List permitted users

                                                        Copy link
                                                        Copy to clipboard
                                                        GET

                                                        /v1/deals/{id}/permittedUsers

                                                        Lists the users permitted to access a deal.

                                                        Path parameters

                                                        id

                                                        integer

                                                        required

                                                        The ID of the deal

                                                        Response
                                                        200

                                                        OK

                                                        Expand all
                                                        Copy code
                                                          • true
                                                          • { ... }

                                                          List all persons associated with a deal

                                                          Copy link
                                                          Copy to clipboard
                                                          GET

                                                          /v1/deals/{id}/persons

                                                          Lists all persons associated with a deal, regardless of whether the person is the primary contact of the deal, or added as a participant.
                                                          If a company uses the Campaigns product, then this endpoint will also return the data.marketing_status field.

                                                          Path parameters

                                                          id

                                                          integer

                                                          required

                                                          The ID of the deal

                                                          Query parameters

                                                          start

                                                          integer

                                                          Pagination start

                                                          Default

                                                          0

                                                          limit

                                                          integer

                                                          Items shown per page

                                                          Response
                                                          200

                                                          OK

                                                          Expand all
                                                          Copy code
                                                            • true
                                                            • [ ... ]
                                                              • { ... }
                                                                • { ... }

                                                                List products attached to a deal

                                                                Copy link
                                                                Copy to clipboard
                                                                GET

                                                                /v1/deals/{id}/products

                                                                Lists products attached to a deal.

                                                                Path parameters

                                                                id

                                                                integer

                                                                required

                                                                The ID of the deal

                                                                Query parameters

                                                                start

                                                                integer

                                                                Pagination start

                                                                Default

                                                                0

                                                                limit

                                                                integer

                                                                Items shown per page

                                                                include_product_data

                                                                number

                                                                Whether to fetch product data along with each attached product (1) or not (0, default)

                                                                Values

                                                                0

                                                                1

                                                                Response
                                                                200

                                                                OK

                                                                Expand all
                                                                Copy code
                                                                  • true
                                                                  • { ... }
                                                                    • { ... }
                                                                      • { ... }

                                                                      Add a deal

                                                                      Copy link
                                                                      Copy to clipboard
                                                                      POST

                                                                      /v1/deals

                                                                      Adds a new deal. Note that you can supply additional custom fields along with the request that are not described here. These custom fields are different for each Pipedrive account and can be recognized by long hashes as keys. To determine which custom fields exists, fetch the dealFields and look for key values. For more information, see the tutorial for adding a deal.

                                                                      Body parameters

                                                                      application/json

                                                                      title

                                                                      string

                                                                      required

                                                                      The title of the deal

                                                                      value

                                                                      string

                                                                      The value of the deal. If omitted, value will be set to 0.

                                                                      currency

                                                                      string

                                                                      The currency of the deal. Accepts a 3-character currency code. If omitted, currency will be set to the default currency of the authorized user.

                                                                      user_id

                                                                      integer

                                                                      The ID of the user which will be the owner of the created deal. If not provided, the user making the request will be used.

                                                                      person_id

                                                                      integer

                                                                      The ID of a person which this deal will be linked to. If the person does not exist yet, it needs to be created first. This property is required unless org_id is specified.

                                                                      org_id

                                                                      integer

                                                                      The ID of an organization which this deal will be linked to. If the organization does not exist yet, it needs to be created first. This property is required unless person_id is specified.

                                                                      pipeline_id

                                                                      integer

                                                                      The ID of the pipeline this deal will be added to. By default, the deal will be added to the first stage of the specified pipeline. Please note that pipeline_id and stage_id should not be used together as pipeline_id will be ignored.

                                                                      stage_id

                                                                      integer

                                                                      The ID of the stage this deal will be added to. Please note that a pipeline will be assigned automatically based on the stage_id. If omitted, the deal will be placed in the first stage of the default pipeline.

                                                                      status

                                                                      string

                                                                      open = Open, won = Won, lost = Lost, deleted = Deleted. If omitted, status will be set to open.

                                                                      Values

                                                                      open

                                                                      won

                                                                      lost

                                                                      deleted

                                                                      expected_close_date

                                                                      string

                                                                      The expected close date of the deal. In ISO 8601 format: YYYY-MM-DD.

                                                                      Format

                                                                      date

                                                                      probability

                                                                      number

                                                                      The success probability percentage of the deal. Used/shown only when deal_probability for the pipeline of the deal is enabled.

                                                                      lost_reason

                                                                      string

                                                                      The optional message about why the deal was lost (to be used when status = lost)

                                                                      visible_to

                                                                      string

                                                                      The visibility of the deal. If omitted, the visibility will be set to the default visibility setting of this item type for the authorized user. Read more about visibility groups here.

                                                                      Essential / Advanced plan

                                                                      ValueDescription
                                                                      1Owner & followers
                                                                      3Entire company

                                                                      Professional / Enterprise plan

                                                                      ValueDescription
                                                                      1Owner only
                                                                      3Owner's visibility group
                                                                      5Owner's visibility group and sub-groups
                                                                      7Entire company

                                                                      Values

                                                                      1

                                                                      3

                                                                      5

                                                                      7

                                                                      add_time

                                                                      string

                                                                      The optional creation date & time of the deal in UTC. Requires admin user API token. Format: YYYY-MM-DD HH:MM:SS

                                                                      Response
                                                                      201

                                                                      Created

                                                                      Expand all
                                                                      Copy code
                                                                        • true
                                                                        • { ... }
                                                                          • { ... }

                                                                          Duplicate deal

                                                                          Copy link
                                                                          Copy to clipboard
                                                                          POST

                                                                          /v1/deals/{id}/duplicate

                                                                          Duplicates a deal.

                                                                          Path parameters

                                                                          id

                                                                          integer

                                                                          required

                                                                          The ID of the deal

                                                                          Response
                                                                          200

                                                                          OK

                                                                          Expand all
                                                                          Copy code
                                                                            • true
                                                                            • { ... }

                                                                            Add a follower to a deal

                                                                            Copy link
                                                                            Copy to clipboard
                                                                            POST

                                                                            /v1/deals/{id}/followers

                                                                            Adds a follower to a deal.

                                                                            Path parameters

                                                                            id

                                                                            integer

                                                                            required

                                                                            The ID of the deal

                                                                            Body parameters

                                                                            application/json

                                                                            user_id

                                                                            integer

                                                                            required

                                                                            The ID of the user

                                                                            Response
                                                                            200

                                                                            OK

                                                                            Expand all
                                                                            Copy code
                                                                              • true
                                                                              • { ... }

                                                                              Add a participant to a deal

                                                                              Copy link
                                                                              Copy to clipboard
                                                                              POST

                                                                              /v1/deals/{id}/participants

                                                                              Adds a participant to a deal.

                                                                              Path parameters

                                                                              id

                                                                              integer

                                                                              required

                                                                              The ID of the deal

                                                                              Body parameters

                                                                              application/json

                                                                              person_id

                                                                              integer

                                                                              required

                                                                              The ID of the person

                                                                              Response
                                                                              200

                                                                              OK

                                                                              Expand all
                                                                              Copy code
                                                                                • true
                                                                                • { ... }
                                                                                  • { ... }

                                                                                  Add a product to a deal

                                                                                  Copy link
                                                                                  Copy to clipboard
                                                                                  POST

                                                                                  /v1/deals/{id}/products

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

                                                                                  Path parameters

                                                                                  id

                                                                                  integer

                                                                                  required

                                                                                  The ID of the deal

                                                                                  Body parameters

                                                                                  application/json

                                                                                  product_id

                                                                                  integer

                                                                                  required

                                                                                  The ID of the product to use

                                                                                  item_price

                                                                                  number

                                                                                  required

                                                                                  The price at which this product will be added to the deal

                                                                                  quantity

                                                                                  integer

                                                                                  required

                                                                                  Quantity – e.g. how many items of this product will be added to the deal

                                                                                  discount_percentage

                                                                                  number

                                                                                  The discount %. If omitted, will be set to 0.

                                                                                  Default

                                                                                  0

                                                                                  duration

                                                                                  number

                                                                                  The duration of the product. If omitted, will be set to 1.

                                                                                  Default

                                                                                  1

                                                                                  duration_unit

                                                                                  string

                                                                                  The unit duration of the product

                                                                                  Values

                                                                                  hourly

                                                                                  daily

                                                                                  weekly

                                                                                  monthly

                                                                                  yearly

                                                                                  product_variation_id

                                                                                  integer

                                                                                  The ID of the product variation to use. When omitted, no variation will be used.

                                                                                  comments

                                                                                  string

                                                                                  A textual comment associated with this product-deal attachment

                                                                                  tax

                                                                                  number

                                                                                  The tax percentage

                                                                                  Default

                                                                                  0

                                                                                  enabled_flag

                                                                                  boolean

                                                                                  Whether the product is enabled for a deal or not. This makes it possible to add products to a deal with a specific price and discount criteria, but keep them disabled, which refrains them from being included in the deal value calculation. When omitted, the product will be marked as enabled by default.

                                                                                  Default

                                                                                  true

                                                                                  Response
                                                                                  200

                                                                                  OK

                                                                                  Expand all
                                                                                  Copy code
                                                                                    • true
                                                                                    • { ... }

                                                                                    Update a deal

                                                                                    Copy link
                                                                                    Copy to clipboard
                                                                                    PUT

                                                                                    /v1/deals/{id}

                                                                                    Updates the properties of a deal. For more information, see the tutorial for updating a deal.

                                                                                    Path parameters

                                                                                    id

                                                                                    integer

                                                                                    required

                                                                                    The ID of the deal

                                                                                    Body parameters

                                                                                    application/json

                                                                                    title

                                                                                    string

                                                                                    The title of the deal

                                                                                    value

                                                                                    string

                                                                                    The value of the deal. If omitted, value will be set to 0.

                                                                                    currency

                                                                                    string

                                                                                    The currency of the deal. Accepts a 3-character currency code. If omitted, currency will be set to the default currency of the authorized user.

                                                                                    user_id

                                                                                    integer

                                                                                    The ID of the user which will be the owner of the created deal. If not provided, the user making the request will be used.

                                                                                    person_id

                                                                                    integer

                                                                                    The ID of a person which this deal will be linked to. If the person does not exist yet, it needs to be created first. This property is required unless org_id is specified.

                                                                                    org_id

                                                                                    integer

                                                                                    The ID of an organization which this deal will be linked to. If the organization does not exist yet, it needs to be created first. This property is required unless person_id is specified.

                                                                                    pipeline_id

                                                                                    integer

                                                                                    The ID of the pipeline this deal will be added to. By default, the deal will be added to the first stage of the specified pipeline. Please note that pipeline_id and stage_id should not be used together as pipeline_id will be ignored.

                                                                                    stage_id

                                                                                    integer

                                                                                    The ID of the stage this deal will be added to. Please note that a pipeline will be assigned automatically based on the stage_id. If omitted, the deal will be placed in the first stage of the default pipeline.

                                                                                    status

                                                                                    string

                                                                                    open = Open, won = Won, lost = Lost, deleted = Deleted. If omitted, status will be set to open.

                                                                                    Values

                                                                                    open

                                                                                    won

                                                                                    lost

                                                                                    deleted

                                                                                    expected_close_date

                                                                                    string

                                                                                    The expected close date of the deal. In ISO 8601 format: YYYY-MM-DD.

                                                                                    Format

                                                                                    date

                                                                                    probability

                                                                                    number

                                                                                    The success probability percentage of the deal. Used/shown only when deal_probability for the pipeline of the deal is enabled.

                                                                                    lost_reason

                                                                                    string

                                                                                    The optional message about why the deal was lost (to be used when status = lost)

                                                                                    visible_to

                                                                                    string

                                                                                    The visibility of the deal. If omitted, the visibility will be set to the default visibility setting of this item type for the authorized user. Read more about visibility groups here.

                                                                                    Essential / Advanced plan

                                                                                    ValueDescription
                                                                                    1Owner & followers
                                                                                    3Entire company

                                                                                    Professional / Enterprise plan

                                                                                    ValueDescription
                                                                                    1Owner only
                                                                                    3Owner's visibility group
                                                                                    5Owner's visibility group and sub-groups
                                                                                    7Entire company

                                                                                    Values

                                                                                    1

                                                                                    3

                                                                                    5

                                                                                    7

                                                                                    Response
                                                                                    200

                                                                                    OK

                                                                                    Expand all
                                                                                    Copy code
                                                                                      • true
                                                                                      • { ... }
                                                                                        • { ... }

                                                                                        Merge two deals

                                                                                        Copy link
                                                                                        Copy to clipboard
                                                                                        PUT

                                                                                        /v1/deals/{id}/merge

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

                                                                                        Path parameters

                                                                                        id

                                                                                        integer

                                                                                        required

                                                                                        The ID of the deal

                                                                                        Body parameters

                                                                                        application/json

                                                                                        merge_with_id

                                                                                        integer

                                                                                        required

                                                                                        The ID of the deal that the deal will be merged with

                                                                                        Response
                                                                                        200

                                                                                        OK

                                                                                        Expand all
                                                                                        Copy code
                                                                                          • true
                                                                                          • { ... }

                                                                                          Update the product attached to a deal

                                                                                          Copy link
                                                                                          Copy to clipboard
                                                                                          PUT

                                                                                          /v1/deals/{id}/products/{product_attachment_id}

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

                                                                                          Path parameters

                                                                                          id

                                                                                          integer

                                                                                          required

                                                                                          The ID of the deal

                                                                                          product_attachment_id

                                                                                          integer

                                                                                          required

                                                                                          The ID of the deal-product (the ID of the product attached to the deal)

                                                                                          Body parameters

                                                                                          application/json

                                                                                          product_id

                                                                                          integer

                                                                                          required

                                                                                          The ID of the product to use

                                                                                          item_price

                                                                                          number

                                                                                          The price at which this product will be added to the deal

                                                                                          quantity

                                                                                          integer

                                                                                          How many items of this product will be added to the deal

                                                                                          discount_percentage

                                                                                          number

                                                                                          The discount %. If omitted, will be set to 0.

                                                                                          Default

                                                                                          0

                                                                                          duration

                                                                                          number

                                                                                          The duration of the product

                                                                                          Default

                                                                                          1

                                                                                          duration_unit

                                                                                          string

                                                                                          The unit duration of the product

                                                                                          Values

                                                                                          hourly

                                                                                          daily

                                                                                          weekly

                                                                                          monthly

                                                                                          yearly

                                                                                          product_variation_id

                                                                                          integer

                                                                                          The ID of the product variation to use. When omitted, no variation will be used.

                                                                                          comments

                                                                                          string

                                                                                          A textual comment associated with this product-deal attachment

                                                                                          tax

                                                                                          number

                                                                                          The tax percentage

                                                                                          Default

                                                                                          0

                                                                                          enabled_flag

                                                                                          boolean

                                                                                          Whether the product is enabled for a deal or not. This makes it possible to add products to a deal with a specific price and discount criteria, but keep them disabled, which refrains them from being included in the deal value calculation. When omitted, the product will be marked as enabled by default.

                                                                                          Default

                                                                                          true

                                                                                          Response
                                                                                          200

                                                                                          OK

                                                                                          Expand all
                                                                                          Copy code
                                                                                            • true
                                                                                            • { ... }

                                                                                            Delete multiple deals in bulk

                                                                                            Copy link
                                                                                            Copy to clipboard
                                                                                            DELETE

                                                                                            /v1/deals

                                                                                            Marks multiple deals as deleted. After 30 days, the deals will be permanently deleted.

                                                                                            Query parameters

                                                                                            ids

                                                                                            string

                                                                                            required

                                                                                            The comma-separated IDs that will be deleted

                                                                                            Response
                                                                                            200

                                                                                            OK

                                                                                            Expand all
                                                                                            Copy code
                                                                                              • true
                                                                                              • { ... }

                                                                                              Delete a deal

                                                                                              Copy link
                                                                                              Copy to clipboard
                                                                                              DELETE

                                                                                              /v1/deals/{id}

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

                                                                                              Path parameters

                                                                                              id

                                                                                              integer

                                                                                              required

                                                                                              The ID of the deal

                                                                                              Response
                                                                                              200

                                                                                              OK

                                                                                              Expand all
                                                                                              Copy code
                                                                                                • true
                                                                                                • { ... }

                                                                                                Delete a follower from a deal

                                                                                                Copy link
                                                                                                Copy to clipboard
                                                                                                DELETE

                                                                                                /v1/deals/{id}/followers/{follower_id}

                                                                                                Deletes a follower from a deal.

                                                                                                Path parameters

                                                                                                id

                                                                                                integer

                                                                                                required

                                                                                                The ID of the deal

                                                                                                follower_id

                                                                                                integer

                                                                                                required

                                                                                                The ID of the follower

                                                                                                Response
                                                                                                200

                                                                                                OK

                                                                                                Expand all
                                                                                                Copy code
                                                                                                  • true
                                                                                                  • { ... }

                                                                                                  Delete a participant from a deal

                                                                                                  Copy link
                                                                                                  Copy to clipboard
                                                                                                  DELETE

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

                                                                                                  Deletes a participant from a deal.

                                                                                                  Path parameters

                                                                                                  id

                                                                                                  integer

                                                                                                  required

                                                                                                  The ID of the deal

                                                                                                  deal_participant_id

                                                                                                  integer

                                                                                                  required

                                                                                                  The ID of the participant of the deal

                                                                                                  Response
                                                                                                  200

                                                                                                  OK

                                                                                                  Expand all
                                                                                                  Copy code
                                                                                                    • true
                                                                                                    • { ... }

                                                                                                    Delete an attached product from a deal

                                                                                                    Copy link
                                                                                                    Copy to clipboard
                                                                                                    DELETE

                                                                                                    /v1/deals/{id}/products/{product_attachment_id}

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

                                                                                                    Path parameters

                                                                                                    id

                                                                                                    integer

                                                                                                    required

                                                                                                    The ID of the deal

                                                                                                    product_attachment_id

                                                                                                    integer

                                                                                                    required

                                                                                                    The product attachment ID

                                                                                                    Response
                                                                                                    200

                                                                                                    OK

                                                                                                    Expand all
                                                                                                    Copy code
                                                                                                      • true
                                                                                                      • { ... }

                                                                                                      Subscribe to Pipedrive’s Developer Newsletter