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

Endpoint is in beta

Request
GET

/api/v2/deals

Query parameters

filter_id

integer

If supplied, only deals matching the specified filter are returned

owner_id

integer

If supplied, only deals owned by the specified user are returned. If filter_id is provided, this is ignored.

person_id

integer

If supplied, only deals linked to the specified person are returned. If filter_id is provided, this is ignored.

org_id

integer

If supplied, only deals linked to the specified organization are returned. If filter_id is provided, this is ignored.

pipeline_id

integer

If supplied, only deals in the specified pipeline are returned. If filter_id is provided, this is ignored.

stage_id

integer

If supplied, only deals in the specified stage are returned. If filter_id is provided, this is ignored.

status

string

Only fetch deals with a specific status. If omitted, all not deleted deals are returned. If set to deleted, deals that have been deleted up to 30 days ago will be included. Multiple statuses can be included as a comma separated array. If filter_id is provided, this is ignored.

Values

open

won

lost

deleted

updated_since

string

If set, only deals with an update_time later than or equal to this time are returned. In RFC3339 format, e.g. 2025-01-01T10:20:00Z.

updated_until

string

If set, only deals with an update_time earlier than this time are returned. In RFC3339 format, e.g. 2025-01-01T10:20:00Z.

sort_by

string

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

Default

id

Values

id

update_time

add_time

sort_direction

string

The sorting direction. Supported values: asc, desc.

Default

asc

Values

asc

desc

include_fields

string

Optional comma separated string array of additional fields to include

Values

next_activity_id

last_activity_id

first_won_time

products_count

files_count

notes_count

followers_count

email_messages_count

activities_count

done_activities_count

undone_activities_count

participants_count

last_incoming_mail_time

last_outgoing_mail_time

custom_fields

string

Optional comma separated string array of custom fields keys to include. If you are only interested in a particular set of custom fields, please use this parameter for faster results and smaller response.
A maximum of 15 keys is allowed.

limit

integer

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

cursor

string

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

Response
200

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

                  Endpoint is in beta

                  Request
                  GET

                  /api/v2/deals/{id}

                  Path parameters

                  id

                  integer

                  required

                  The ID of the deal

                  Query parameters

                  include_fields

                  string

                  Optional comma separated string array of additional fields to include

                  Values

                  next_activity_id

                  last_activity_id

                  first_won_time

                  products_count

                  files_count

                  notes_count

                  followers_count

                  email_messages_count

                  activities_count

                  done_activities_count

                  undone_activities_count

                  participants_count

                  last_incoming_mail_time

                  last_outgoing_mail_time

                  custom_fields

                  string

                  Optional comma separated string array of custom fields keys to include. If you are only interested in a particular set of custom fields, please use this parameter for faster results and smaller response.
                  A maximum of 15 keys is allowed.

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

                                                                            Endpoint is in beta

                                                                            Request
                                                                            POST

                                                                            /api/v2/deals

                                                                            Body parameters

                                                                            application/json

                                                                            title

                                                                            string

                                                                            required

                                                                            The title of the deal

                                                                            owner_id

                                                                            integer

                                                                            The ID of the user who owns the deal

                                                                            person_id

                                                                            integer

                                                                            The ID of the person linked to the deal

                                                                            org_id

                                                                            integer

                                                                            The ID of the organization linked to the deal

                                                                            pipeline_id

                                                                            integer

                                                                            The ID of the pipeline associated with the deal

                                                                            stage_id

                                                                            integer

                                                                            The ID of the deal stage

                                                                            value

                                                                            number

                                                                            The value of the deal

                                                                            currency

                                                                            string

                                                                            The currency associated with the deal

                                                                            add_time

                                                                            string

                                                                            The creation date and time of the deal

                                                                            update_time

                                                                            string

                                                                            The last updated date and time of the deal

                                                                            stage_change_time

                                                                            string

                                                                            The last updated date and time of the deal stage

                                                                            is_deleted

                                                                            boolean

                                                                            Whether the deal is deleted or not

                                                                            status

                                                                            string

                                                                            The status of the deal

                                                                            probability

                                                                            number

                                                                            The success probability percentage of the deal

                                                                            lost_reason

                                                                            string

                                                                            The reason for losing the deal. Can only be set if deal status is lost.

                                                                            visible_to

                                                                            integer

                                                                            The visibility of the deal

                                                                            close_time

                                                                            string

                                                                            The date and time of closing the deal. Can only be set if deal status is won or lost.

                                                                            won_time

                                                                            string

                                                                            The date and time of changing the deal status as won. Can only be set if deal status is won.

                                                                            lost_time

                                                                            string

                                                                            The date and time of changing the deal status as lost. Can only be set if deal status is lost.

                                                                            expected_close_date

                                                                            string

                                                                            The expected close date of the deal

                                                                            Format

                                                                            date

                                                                            label_ids

                                                                            array

                                                                            The IDs of labels assigned to the deal

                                                                            Response
                                                                            200

                                                                            OK

                                                                            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

                                                                                      Not possible to disable the product if the deal has installments associated and the product is the last one enabled

                                                                                      Not possible to enable the product if the deal has installments associated and the product is recurring

                                                                                      Default

                                                                                      true

                                                                                      tax_method

                                                                                      string

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

                                                                                      Values

                                                                                      exclusive

                                                                                      inclusive

                                                                                      none

                                                                                      discount_type

                                                                                      string

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

                                                                                      Default

                                                                                      percentage

                                                                                      Values

                                                                                      percentage

                                                                                      amount

                                                                                      product_variation_id

                                                                                      integer

                                                                                      The ID of the product variation

                                                                                      billing_frequency

                                                                                      string

                                                                                      Only available in Advanced and above plans

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

                                                                                      To set billing_frequency different than one-time, the deal must not have installments associated

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

                                                                                      Default

                                                                                      one-time

                                                                                      Values

                                                                                      one-time

                                                                                      annually

                                                                                      semi-annually

                                                                                      quarterly

                                                                                      monthly

                                                                                      weekly

                                                                                      billing_frequency_cycles

                                                                                      integer

                                                                                      Only available in Advanced and above plans

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

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

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

                                                                                          Endpoint is in beta

                                                                                          Request
                                                                                          PATCH

                                                                                          /api/v2/deals/{id}

                                                                                          Path parameters

                                                                                          id

                                                                                          integer

                                                                                          required

                                                                                          The ID of the deal

                                                                                          Body parameters

                                                                                          application/json

                                                                                          title

                                                                                          string

                                                                                          The title of the deal

                                                                                          owner_id

                                                                                          integer

                                                                                          The ID of the user who owns the deal

                                                                                          person_id

                                                                                          integer

                                                                                          The ID of the person linked to the deal

                                                                                          org_id

                                                                                          integer

                                                                                          The ID of the organization linked to the deal

                                                                                          pipeline_id

                                                                                          integer

                                                                                          The ID of the pipeline associated with the deal

                                                                                          stage_id

                                                                                          integer

                                                                                          The ID of the deal stage

                                                                                          value

                                                                                          number

                                                                                          The value of the deal

                                                                                          currency

                                                                                          string

                                                                                          The currency associated with the deal

                                                                                          add_time

                                                                                          string

                                                                                          The creation date and time of the deal

                                                                                          update_time

                                                                                          string

                                                                                          The last updated date and time of the deal

                                                                                          stage_change_time

                                                                                          string

                                                                                          The last updated date and time of the deal stage

                                                                                          is_deleted

                                                                                          boolean

                                                                                          Whether the deal is deleted or not

                                                                                          status

                                                                                          string

                                                                                          The status of the deal

                                                                                          probability

                                                                                          number

                                                                                          The success probability percentage of the deal

                                                                                          lost_reason

                                                                                          string

                                                                                          The reason for losing the deal. Can only be set if deal status is lost.

                                                                                          visible_to

                                                                                          integer

                                                                                          The visibility of the deal

                                                                                          close_time

                                                                                          string

                                                                                          The date and time of closing the deal. Can only be set if deal status is won or lost.

                                                                                          won_time

                                                                                          string

                                                                                          The date and time of changing the deal status as won. Can only be set if deal status is won.

                                                                                          lost_time

                                                                                          string

                                                                                          The date and time of changing the deal status as lost. Can only be set if deal status is lost.

                                                                                          expected_close_date

                                                                                          string

                                                                                          The expected close date of the deal

                                                                                          Format

                                                                                          date

                                                                                          label_ids

                                                                                          array

                                                                                          The IDs of labels assigned to the deal

                                                                                          Response
                                                                                          200

                                                                                          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

                                                                                              Not possible to disable the product if the deal has installments associated and the product is the last one enabled

                                                                                              Not possible to enable the product if the deal has installments associated and the product is recurring

                                                                                              Default

                                                                                              true

                                                                                              tax_method

                                                                                              string

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

                                                                                              Values

                                                                                              exclusive

                                                                                              inclusive

                                                                                              none

                                                                                              discount_type

                                                                                              string

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

                                                                                              Default

                                                                                              percentage

                                                                                              Values

                                                                                              percentage

                                                                                              amount

                                                                                              product_variation_id

                                                                                              integer

                                                                                              The ID of the product variation

                                                                                              billing_frequency

                                                                                              string

                                                                                              Only available in Advanced and above plans

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

                                                                                              To set billing_frequency different than one-time, the deal must not have installments associated

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

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

                                                                                                    Endpoint is in beta

                                                                                                    Request
                                                                                                    DELETE

                                                                                                    /api/v2/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

                                                                                                          Not possible to delete the attached product if the deal has installments associated and the product is the last one enabled

                                                                                                          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