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

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

API v1
Request
GET

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

        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.

        API v1
        Request
        GET

        /v1/deals/collection

        Query parameters

        cursor

        string

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

        limit

        integer

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

        since

        string

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

        until

        string

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

        user_id

        integer

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

        stage_id

        integer

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

        status

        string

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

        Values

        open

        won

        lost

        deleted

        Response
        200

        OK

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

            Search deals

            Copy link

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

            API v1
            API v2

            Endpoint is in beta

            Request
            GET

            /api/v2/deals/search

            Query parameters

            term

            string

            required

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

            fields

            string

            A comma-separated string array. The fields to perform the search from. Defaults to all of them. Only the following custom field types are searchable: address, varchar, text, varchar_auto, double, monetary and phone. Read more about searching by custom fields here.

            Values

            custom_fields

            notes

            title

            exact_match

            boolean

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

            person_id

            integer

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

            organization_id

            integer

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

            status

            string

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

            Values

            open

            won

            lost

            include_fields

            string

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

            Values

            deal.cc_email

            limit

            integer

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

            cursor

            string

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

            Response
            200

            OK

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

                Get deals summary

                Copy link

                Returns a summary of all the deals.

                API v1
                Request
                GET

                /v1/deals/summary

                Query parameters

                status

                string

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

                Values

                open

                won

                lost

                filter_id

                integer

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

                user_id

                integer

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

                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

                  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.

                  API v1
                  Request
                  GET

                  /v1/deals/timeline

                  Query parameters

                  start_date

                  string

                  required

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

                  Format

                  date

                  interval

                  string

                  required

                  The type of the interval

                  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

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

                    API v1
                    Request
                    GET

                    /v1/deals/{id}

                    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

                          Lists activities associated with a deal.

                          API v1
                          Request
                          GET

                          /v1/deals/{id}/activities

                          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 updates about deal field values

                                Copy link

                                Lists updates about field values of a deal.

                                API v1
                                Request
                                GET

                                /v1/deals/{id}/changelog

                                Path parameters

                                id

                                integer

                                required

                                The ID of the deal

                                Query parameters

                                cursor

                                string

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

                                limit

                                integer

                                Items shown per page

                                Response
                                200

                                OK

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

                                    List files attached to a deal

                                    Copy link

                                    Lists files associated with a deal.

                                    API v1
                                    Request
                                    GET

                                    /v1/deals/{id}/files

                                    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

                                        Lists updates about a deal.

                                        API v1
                                        Request
                                        GET

                                        /v1/deals/{id}/flow

                                        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

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

                                              API v1
                                              Request
                                              GET

                                              /v1/deals/{id}/participantsChangelog

                                              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

                                                  Lists the followers of a deal.

                                                  API v1
                                                  Request
                                                  GET

                                                  /v1/deals/{id}/followers

                                                  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

                                                      Lists mail messages associated with a deal.

                                                      API v1
                                                      Request
                                                      GET

                                                      /v1/deals/{id}/mailMessages

                                                      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

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

                                                          API v1
                                                          Request
                                                          GET

                                                          /v1/deals/{id}/participants

                                                          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

                                                                Lists the users permitted to access a deal.

                                                                API v1
                                                                Request
                                                                GET

                                                                /v1/deals/{id}/permittedUsers

                                                                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

                                                                  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.

                                                                  API v1
                                                                  Request
                                                                  GET

                                                                  /v1/deals/{id}/persons

                                                                  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

                                                                        Lists products attached to a deal.

                                                                        API v1
                                                                        API v2

                                                                        Endpoint is in beta

                                                                        Request
                                                                        GET

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

                                                                        Path parameters

                                                                        id

                                                                        integer

                                                                        required

                                                                        The ID of the deal

                                                                        Query parameters

                                                                        cursor

                                                                        string

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

                                                                        limit

                                                                        integer

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

                                                                        sort_by

                                                                        string

                                                                        The field to sort by. Supported fields: id, add_time, update_time

                                                                        Default

                                                                        id

                                                                        Values

                                                                        id

                                                                        add_time

                                                                        update_time

                                                                        sort_direction

                                                                        string

                                                                        The sorting direction. Supported values: asc, desc

                                                                        Default

                                                                        asc

                                                                        Values

                                                                        asc

                                                                        desc

                                                                        Response
                                                                        200

                                                                        OK

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

                                                                            Get deal products of several deals

                                                                            Copy link

                                                                            Returns data about products attached to deals

                                                                            API v2

                                                                            Endpoint is in beta

                                                                            Request
                                                                            GET

                                                                            /api/v2/deals/products

                                                                            Query parameters

                                                                            deal_ids

                                                                            array

                                                                            required

                                                                            An array of integers with the IDs of the deals for which the attached products will be returned. A maximum of 100 deal IDs can be provided

                                                                            cursor

                                                                            string

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

                                                                            limit

                                                                            integer

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

                                                                            sort_by

                                                                            string

                                                                            The field to sort by. Supported fields: id, deal_id, add_time, update_time

                                                                            Default

                                                                            id

                                                                            Values

                                                                            id

                                                                            deal_id

                                                                            add_time

                                                                            update_time

                                                                            sort_direction

                                                                            string

                                                                            The sorting direction. Supported values: asc, desc

                                                                            Default

                                                                            asc

                                                                            Values

                                                                            asc

                                                                            desc

                                                                            Response
                                                                            200

                                                                            OK

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

                                                                                List discounts added to a deal

                                                                                Copy link

                                                                                Lists discounts attached to a deal.

                                                                                API v2

                                                                                Endpoint is in beta

                                                                                Request
                                                                                GET

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

                                                                                Path parameters

                                                                                id

                                                                                integer

                                                                                required

                                                                                The ID of the deal

                                                                                Response
                                                                                200

                                                                                OK

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

                                                                                  Add a deal

                                                                                  Copy link

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

                                                                                  API v1
                                                                                  Request
                                                                                  POST

                                                                                  /v1/deals

                                                                                  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

                                                                                  origin_id

                                                                                  string

                                                                                  The optional ID to further distinguish the origin of the deal - e.g. Which API integration created this deal. If omitted, origin_id will be set to null.

                                                                                  channel

                                                                                  integer

                                                                                  The ID of Marketing channel this deal was created from. Provided value must be one of the channels configured for your company. You can fetch allowed values with GET /v1/dealFields. If omitted, channel will be set to null.

                                                                                  channel_id

                                                                                  string

                                                                                  The optional ID to further distinguish the Marketing channel. If omitted, channel_id will be set to null.

                                                                                  add_time

                                                                                  string

                                                                                  The optional creation date & time of the deal in UTC. 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

                                                                                      Duplicates a deal.

                                                                                      API v1
                                                                                      Request
                                                                                      POST

                                                                                      /v1/deals/{id}/duplicate

                                                                                      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

                                                                                        Adds a follower to a deal.

                                                                                        API v1
                                                                                        Request
                                                                                        POST

                                                                                        /v1/deals/{id}/followers

                                                                                        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

                                                                                          Adds a participant to a deal.

                                                                                          API v1
                                                                                          Request
                                                                                          POST

                                                                                          /v1/deals/{id}/participants

                                                                                          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

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

                                                                                              API v1
                                                                                              API v2

                                                                                              Endpoint is in beta

                                                                                              Request
                                                                                              POST

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

                                                                                              Path parameters

                                                                                              id

                                                                                              integer

                                                                                              required

                                                                                              The ID of the deal

                                                                                              Body parameters

                                                                                              application/json

                                                                                              product_id

                                                                                              integer

                                                                                              required

                                                                                              The ID of the product

                                                                                              item_price

                                                                                              number

                                                                                              required

                                                                                              The price value of the product

                                                                                              quantity

                                                                                              number

                                                                                              required

                                                                                              The quantity of the product

                                                                                              tax

                                                                                              number

                                                                                              The product tax

                                                                                              Default

                                                                                              0

                                                                                              comments

                                                                                              string

                                                                                              The comments of the product

                                                                                              discount

                                                                                              number

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

                                                                                              Default

                                                                                              0

                                                                                              is_enabled

                                                                                              boolean

                                                                                              Whether this product is enabled for the deal

                                                                                              Default

                                                                                              true

                                                                                              tax_method

                                                                                              string

                                                                                              The tax option to be applied to the products. When using inclusive, the tax percentage will already be included in the price. When using exclusive, the tax will not be included in the price. When using none, no tax will be added. Use the tax field for defining the tax percentage amount. By default, the user setting value for tax options will be used. Changing this in one product affects the rest of the products attached to the deal

                                                                                              Values

                                                                                              exclusive

                                                                                              inclusive

                                                                                              none

                                                                                              discount_type

                                                                                              string

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

                                                                                              Default

                                                                                              percentage

                                                                                              Values

                                                                                              percentage

                                                                                              amount

                                                                                              product_variation_id

                                                                                              integer

                                                                                              The ID of the product variation

                                                                                              billing_frequency

                                                                                              string

                                                                                              Only available in Advanced and above plans

                                                                                              How often a customer is billed for access to a service or product

                                                                                              A deal can have up to 20 products attached with billing_frequency different than one-time

                                                                                              Default

                                                                                              one-time

                                                                                              Values

                                                                                              one-time

                                                                                              annually

                                                                                              semi-annually

                                                                                              quarterly

                                                                                              monthly

                                                                                              weekly

                                                                                              billing_frequency_cycles

                                                                                              integer

                                                                                              Only available in Advanced and above plans

                                                                                              The number of times the billing frequency repeats for a product in a deal

                                                                                              When billing_frequency is set to one-time, this field must be null

                                                                                              For all the other values of billing_frequency, null represents a product billed indefinitely

                                                                                              Must be a positive integer less or equal to 312

                                                                                              Default

                                                                                              null

                                                                                              billing_start_date

                                                                                              string

                                                                                              Only available in Advanced and above plans

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

                                                                                              Format

                                                                                              YYYY-MM-DD

                                                                                              Default

                                                                                              null

                                                                                              Response
                                                                                              201

                                                                                              Created

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

                                                                                                Add a discount to a deal

                                                                                                Copy link

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

                                                                                                API v2

                                                                                                Endpoint is in beta

                                                                                                Request
                                                                                                POST

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

                                                                                                Path parameters

                                                                                                id

                                                                                                integer

                                                                                                required

                                                                                                The ID of the deal

                                                                                                Body parameters

                                                                                                application/json

                                                                                                description

                                                                                                string

                                                                                                required

                                                                                                The name of the discount.

                                                                                                amount

                                                                                                number

                                                                                                required

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

                                                                                                type

                                                                                                string

                                                                                                required

                                                                                                Determines whether the discount is applied as a percentage or a fixed amount.

                                                                                                Values

                                                                                                percentage

                                                                                                amount

                                                                                                Response
                                                                                                201

                                                                                                Created

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

                                                                                                  Update a deal

                                                                                                  Copy link

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

                                                                                                  API v1
                                                                                                  Request
                                                                                                  PUT

                                                                                                  /v1/deals/{id}

                                                                                                  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

                                                                                                  channel

                                                                                                  integer

                                                                                                  The ID of Marketing channel this deal was created from. Provided value must be one of the channels configured for your company which you can fetch with GET /v1/dealFields.

                                                                                                  channel_id

                                                                                                  string

                                                                                                  The optional ID to further distinguish the Marketing channel.

                                                                                                  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

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

                                                                                                      API v1
                                                                                                      Request
                                                                                                      PUT

                                                                                                      /v1/deals/{id}/merge

                                                                                                      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

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

                                                                                                        API v1
                                                                                                        API v2

                                                                                                        Endpoint is in beta

                                                                                                        Request
                                                                                                        PATCH

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

                                                                                                        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

                                                                                                        item_price

                                                                                                        number

                                                                                                        The price value of the product

                                                                                                        quantity

                                                                                                        number

                                                                                                        The quantity of the product

                                                                                                        tax

                                                                                                        number

                                                                                                        The product tax

                                                                                                        Default

                                                                                                        0

                                                                                                        comments

                                                                                                        string

                                                                                                        The comments of the product

                                                                                                        discount

                                                                                                        number

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

                                                                                                        Default

                                                                                                        0

                                                                                                        is_enabled

                                                                                                        boolean

                                                                                                        Whether this product is enabled for the deal

                                                                                                        Default

                                                                                                        true

                                                                                                        tax_method

                                                                                                        string

                                                                                                        The tax option to be applied to the products. When using inclusive, the tax percentage will already be included in the price. When using exclusive, the tax will not be included in the price. When using none, no tax will be added. Use the tax field for defining the tax percentage amount. By default, the user setting value for tax options will be used. Changing this in one product affects the rest of the products attached to the deal

                                                                                                        Values

                                                                                                        exclusive

                                                                                                        inclusive

                                                                                                        none

                                                                                                        discount_type

                                                                                                        string

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

                                                                                                        Default

                                                                                                        percentage

                                                                                                        Values

                                                                                                        percentage

                                                                                                        amount

                                                                                                        product_variation_id

                                                                                                        integer

                                                                                                        The ID of the product variation

                                                                                                        billing_frequency

                                                                                                        string

                                                                                                        Only available in Advanced and above plans

                                                                                                        How often a customer is billed for access to a service or product

                                                                                                        A deal can have up to 20 products attached with billing_frequency different than one-time

                                                                                                        Values

                                                                                                        one-time

                                                                                                        annually

                                                                                                        semi-annually

                                                                                                        quarterly

                                                                                                        monthly

                                                                                                        weekly

                                                                                                        billing_frequency_cycles

                                                                                                        integer

                                                                                                        Only available in Advanced and above plans

                                                                                                        The number of times the billing frequency repeats for a product in a deal

                                                                                                        When billing_frequency is set to one-time, this field must be null

                                                                                                        For all the other values of billing_frequency, null represents a product billed indefinitely

                                                                                                        Must be a positive integer less or equal to 312

                                                                                                        billing_start_date

                                                                                                        string

                                                                                                        Only available in Advanced and above plans

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

                                                                                                        Format

                                                                                                        YYYY-MM-DD

                                                                                                        Response
                                                                                                        200

                                                                                                        OK

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

                                                                                                          Update a discount added to a deal

                                                                                                          Copy link

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

                                                                                                          API v2

                                                                                                          Endpoint is in beta

                                                                                                          Request
                                                                                                          PATCH

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

                                                                                                          Path parameters

                                                                                                          id

                                                                                                          integer

                                                                                                          required

                                                                                                          The ID of the deal

                                                                                                          discount_id

                                                                                                          integer

                                                                                                          required

                                                                                                          The ID of the discount

                                                                                                          Body parameters

                                                                                                          application/json

                                                                                                          description

                                                                                                          string

                                                                                                          The name of the discount.

                                                                                                          amount

                                                                                                          number

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

                                                                                                          type

                                                                                                          string

                                                                                                          Determines whether the discount is applied as a percentage or a fixed amount.

                                                                                                          Values

                                                                                                          percentage

                                                                                                          amount

                                                                                                          Response
                                                                                                          200

                                                                                                          OK

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

                                                                                                            Delete multiple deals in bulk

                                                                                                            Copy link

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

                                                                                                            API v1
                                                                                                            Request
                                                                                                            DELETE

                                                                                                            /v1/deals

                                                                                                            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

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

                                                                                                              API v1
                                                                                                              Request
                                                                                                              DELETE

                                                                                                              /v1/deals/{id}

                                                                                                              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

                                                                                                                Deletes a follower from a deal.

                                                                                                                API v1
                                                                                                                Request
                                                                                                                DELETE

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

                                                                                                                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

                                                                                                                  Deletes a participant from a deal.

                                                                                                                  API v1
                                                                                                                  Request
                                                                                                                  DELETE

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

                                                                                                                  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

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

                                                                                                                    API v1
                                                                                                                    API v2

                                                                                                                    Endpoint is in beta

                                                                                                                    Request
                                                                                                                    DELETE

                                                                                                                    /api/v2/deals/{id}/products/{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
                                                                                                                      • { ... }

                                                                                                                      Delete a discount from a deal

                                                                                                                      Copy link

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

                                                                                                                      API v2

                                                                                                                      Endpoint is in beta

                                                                                                                      Request
                                                                                                                      DELETE

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

                                                                                                                      Path parameters

                                                                                                                      id

                                                                                                                      integer

                                                                                                                      required

                                                                                                                      The ID of the deal

                                                                                                                      discount_id

                                                                                                                      integer

                                                                                                                      required

                                                                                                                      The ID of the discount

                                                                                                                      Response
                                                                                                                      200

                                                                                                                      OK

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

                                                                                                                        Subscribe to Pipedrive’s Developer Newsletter