go to pipedrive.com
Log inSign up

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

            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
                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
                  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
                    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
                          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
                                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
                                    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 updates about participants of a deal

                                          Copy link
                                          GET

                                          /v1/deals/{id}/participantsChangelog

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

                                          Path parameters

                                          id

                                          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

                                          OK

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

                                              List followers of a deal

                                              Copy link
                                              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
                                                  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
                                                      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
                                                            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
                                                              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
                                                                    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
                                                                          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.

                                                                          label

                                                                          array

                                                                          The array of the labels IDs.

                                                                          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

                                                                          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

                                                                          won_time

                                                                          string

                                                                          The optional date and time of changing the deal status as won in UTC. Format: YYYY-MM-DD HH:MM:SS. Can be set only when deal status is already Won. Can not be used together with lost_time.

                                                                          lost_time

                                                                          string

                                                                          The optional date and time of changing the deal status as lost in UTC. Format: YYYY-MM-DD HH:MM:SS. Can be set only when deal status is already Lost. Can not be used together with won_time.

                                                                          close_time

                                                                          string

                                                                          The optional date and time of closing the deal in UTC. Format: YYYY-MM-DD HH:MM:SS.

                                                                          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
                                                                          201

                                                                          Created

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

                                                                              Duplicate deal

                                                                              Copy link
                                                                              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
                                                                                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
                                                                                  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
                                                                                      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

                                                                                      number

                                                                                      The value of the discount. The discount_type field can be used to specify whether the value is an amount or a percentage.

                                                                                      Default

                                                                                      0

                                                                                      discount_type

                                                                                      string

                                                                                      The type of the discount's value.

                                                                                      Default

                                                                                      percentage

                                                                                      Values

                                                                                      percentage

                                                                                      amount

                                                                                      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

                                                                                      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

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

                                                                                        label

                                                                                        array

                                                                                        Array of the deal labels IDs.

                                                                                        currency

                                                                                        string

                                                                                        The currency of the deal. Accepts a 3-character currency code.

                                                                                        user_id

                                                                                        integer

                                                                                        The ID of the user which will be the new owner of the deal.

                                                                                        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.

                                                                                        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.

                                                                                        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.

                                                                                        status

                                                                                        string

                                                                                        open = Open, won = Won, lost = Lost, deleted = Deleted.

                                                                                        Values

                                                                                        open

                                                                                        won

                                                                                        lost

                                                                                        deleted

                                                                                        won_time

                                                                                        string

                                                                                        The optional date and time of changing the deal status as won in UTC. Format: YYYY-MM-DD HH:MM:SS. Can be set only when deal status is already Won. Can not be used together with lost_time.

                                                                                        lost_time

                                                                                        string

                                                                                        The optional date and time of changing the deal status as lost in UTC. Format: YYYY-MM-DD HH:MM:SS. Can be set only when deal status is already Lost. Can not be used together with won_time.

                                                                                        close_time

                                                                                        string

                                                                                        The optional date and time of closing the deal in UTC. Format: YYYY-MM-DD HH:MM:SS.

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

                                                                                              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

                                                                                              number

                                                                                              The value of the discount. The discount_type field can be used to specify whether the value is an amount or a percentage.

                                                                                              Default

                                                                                              0

                                                                                              discount_type

                                                                                              string

                                                                                              The type of the discount's value.

                                                                                              Default

                                                                                              percentage

                                                                                              Values

                                                                                              percentage

                                                                                              amount

                                                                                              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

                                                                                              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.

                                                                                              Values

                                                                                              exclusive

                                                                                              inclusive

                                                                                              none

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