Postponed: PermissionSets API breaking changes

Note: If you are simply using our Pipedrive web app and don’t have any custom integrations that you (or a developer) has built, you should have nothing to worry about.
If you have, or someone else has, built a custom integration that you are currently using to enhance your Pipedrive experience, please forward this information to the relevant stakeholders.

Recently on July 8, 2021, we announced breaking changes for three PermissionSets API endpoints.

Based on your feedback and to give you more time to align with our API changes, we’ve decided to postpone the breaking changes to our PermissionSets API from July 26, 2021 to September 1, 2021.

Who is affected?

All consumers of the listed API endpoints are affected in case they

• specifically expect Permission Set ID to be an integer
• rely on the removed Permission Set Assignment id field

Published on July 23, 2021

Breaking change for POST /stages endpoint

What is going to change?

The body parameter name of the POST /stages endpoint is a required property (both under the hood and in the documentation), but its existence is not validated when making the request. The endpoint returns 201 even when there is no value given to the name body parameter.

We are going to add validation to the name body parameter when requesting the POST /stages endpoint. When the value is not present, then the response error will be 400 “Bad request”.

Why is it going to change?

The name body parameter should be required according to the documentation and common sense.

Who is affected?

Anyone with functionality built on top of using the endpoint without specifying the stage name. Although it is marked as required in our API Reference page documentation, we encourage you to please check how you are using the endpoint.

Published on July 19, 2021

Fix in POST /pipelines endpoint documentation

We had the name parameter not marked as required in the documentation of POST /v1/pipelines endpoint in our API Reference, but under the hood it has always been a required parameter. We have now corrected the documentation and assigned the “required” flag to the name parameter.

Published on July 9, 2021

PermissionSets API breaking changes

There are the following breaking changes happening to PermissionSets API:

What is going to change?

1. The Permission Set ID format will be changed from integer to UUID (universally unique identifier) string. This means that the current IDs will be replaced with new values both in the endpoint path and the response body for the following three endpoints:

• GET /v1/permissionSets
• GET /v1/permissionSets/:id
• GET /v1/permissionSets/:id/assignments

2. The response of GET /v1/permissionSets/:id/assignments will no longer include the id field per assignment. An assignment is an object which currently includes the following fields

• id (which will be removed)
• user_id
• permission_set_id
• name (the name of the PermissionSet)

3. Permission Set objects returned from GET /v1/permissionSets and GET /v1/permissionSets/:id will temporarily (for the next 2 months) have an additional field old_id of type integer, which will contain the old ID value

4. Permission Set Assignment objects returned from GET /v1/permissionSets/:id/assignments will temporarily (for the next 2 months) have an additional field permission_set_id_old of type integer, which will contain the old Permission Set ID value

Why is it going to change?

We are updating our data storage in preparation for providing the new Permission Set functionality in the near future.

Who is affected?

All consumers of the listed API endpoints are affected in case they

• specifically expect Permission Set ID to be an integer
• rely on the removed Permission Set Assignment id field

Published on July 8, 2021

Removal of App Extensions for Products

What has changed?

Support for app extensions inside Products List view, including basic app actions and embedded app actions, is now discontinued.

Why was it discontinued?

It was discontinued due to a technical change. As we have noticed that no submitted app has been making use of app extensions for Products in List view, we decided to discontinue support for it.

Should you be keen on using basic app actions or embedded app actions inside Product details or list views, please contact us directly at [email protected] and tell us your use case. We’d be very happy to hear from you!

Published on July 6, 2021

Error response correction for Search API

What is going to change?

We are going to update the current incorrect error response to match Pipedrive API’s core concepts of responses for the following Search endpoints:

• GET /v1/deals/search
• GET /v1/itemSearch
• GET /itemSearch/field
• GET /organizations/search
• GET /persons/search

Here is an example of a correct error response which will be applied for the endpoints listed above:

{
 "success": false,
 "error": "Requested service is not available", //main error message
 "error_info": "Please check developers.pipedrive.com",
 "data": null,
 "additional data": null
}

Who is affected?

Anyone with functionality built on top of the previous behavior will need to alter their code.

Published on July 1, 2021

Breaking bug fix in POST /deals endpoint

What is going to change?

When creating a Deal via the Pipedrive API, it will start requiring the new Deal to be linked to a Person or an Organization. Therefore, when adding a Deal via the the POST /deals endpoint, one has to insert a value for either one of these body parameters:

• person_id - ID of the Person this Deal will be associated with
• org_id - ID of the Organization this Deal will be associated with

We will be adding the red ‘required’ label to both of these body parameters in our API Reference documentation when the given grace time is over.

Why is it going to change?

In the Pipedrive web app, it has always been mandatory to have the newly created Deal linked with a Person or an Organization. This change is needed to keep the data in Pipedrive consistent. We wish to avoid unexpected results forPipedrive users when they use the Product and other features with the Deal being not linked to a Person or an Organization.

Who is affected?

Anyone with functionality built on top of the previous behavior will need to alter their code.

Published on June 30, 2021

New field for Webhooks

We've publicly documented the change_source field for Webhooks. This field allows you to see where the webhook has been triggered from.

Only the following 2 values are possible for this field:

• app - the webhook is triggered from the Pipedrive web app
• api - the webhook is triggered through the API

Published on June 22, 2021

New field in the API response of the related_objects object

What is going to change?

We have added a new field owner_id to the person object of the related_objects in the API response. This field shows the owner ID of the user who owns the Person record. The value of the field is always an integer.

Here’s the code example of the new response in JSON:

{
  "data": [...],
  "additional_data": {...},
  "related_objects": {
    "person": {
      "1": {
        "id": 1,
        "name": "person name",
        "active_flag": true,
        "email": [
          {
            "label": "work",
            "value": "[email protected]",
            "primary": true
          }
        ],
        "phone": [
          {
            "label": "work",
            "value": "5555555",
            "primary": true
          }
        ],
        "owner_id": 1111111
      }
    }
  }
}
}

Why is it added?

In addition to fixing a bug in our web app, this update will also bring more consistency to our API as the field owner_id is currently present only in the organization object of the related_objects.

Who is affected?

Users who are referring to the person object of the related_objects in webhooks and when using the following 15 API endpoints:

• GET /v1/activities
• GET /v1/activities/{id}
• POST /v1/activities
• PUT /v1/activities/{id}
• GET /v1/deals
• GET /v1/deals/{id}
• GET /v1/deals/{id}/activities
• GET /v1/deals/{id}/flow
• GET /v1/deals/{id}/participants
• POST /v1/deals
• POST /v1/deals/{id}/participants
• PUT /v1/deals/{id}
• GET /v1/organizations/{id}/deals
• GET /v1/persons/{id}/deals
• GET /v1/persons/{id}/flow

Published on June 3, 2021

New field lead_default_visibility in the Roles API

Users already had control over the default visibility for other entities (Organizations, People, Deals and Products). Now, the Users can also define the default visibility for their leads.

What has been added to the Roles API?

In order for our Users to be able to define the default visibility for their leads also via the API, we have extended the responses of three Roles’ endpoints.

The possible values for the lead_default_visibility field depend on the plan the company using the Roles API is on:

Essential / Advanced plan:

• 1 (Owner & followers)
• 3 (Entire company)

Professional / Enterprise plan:

• 1 (Owner & followers)
• 3 (Owners visibility group)
• 5 (Owners visibility group and below)
• 7 (Entire company)

Which Roles API endpoints are affected?

1. GET /v1/roles/{id}/settings - we updated the response to include lead_default_visibility, so now this endpoint will always return:

{
 "success": true,
 "data": {
  (...)
  "lead_default_visibility": 1
 }
}

2. POST /v1/roles/{id}/settings - the request can include and return the field lead_default_visibility in the body (if updating the lead visibility)

{
 "success": true,
 "data": {
  "id": 2,
  "lead_default_visibility": 1
 }
}

3. GET /v1/roles/{id} - we updated the response to include lead_default_visibility, so now this endpoint will always return

{
 "success": true,
 "data": { ... },
 "additional_data": {
  "settings": {
   (...)
   "lead_default_visibility": 1
  }
 }
}

Published on June 3, 2021

Reassessment of the limitation of custom field’s options

Regarding the recent limitation for 2 custom field type's options, after further user testing, our product team has risen the limit of options single option and multiple options custom fields can have to 10,000 options per custom field. When the limit of 10,000 options has been reached the following error message will be displayed: "You reached the limit of 10000 options per field. Remove some options to be able to save."

Published on May 26, 2021

New fields in GET /deals/summary endpoint response

We have added two new fields to the GET /deals/summary endpoint response:

• is_custom_currency - a boolean showing whether the currency is considered custom
• total_custom_currency_count - an integer showing the total count of currencies for which is_custom_currency is true

Published on May 19, 2021

Limitation of custom field’s options

Starting from May 12, 2021, we will be limiting the amount of options custom fields with type “Multiple option” and “Single option” can have. The limit will be 500 options per custom field.

When the amount of options per custom field is reached, an error message will be displayed in the API response. The error message will be as follows:

"You reached the limit of 500 options per field. Remove some options to be able to save."

In case there is a need for more options to be added to a custom field, the user will have to delete some existing options from that field to fit into the limit.

Nothing will break for the users who already have created more than 500 options for their custom fields, but if they decide to add more options they would need to remove all the extra options which exceed the 500 limit.

Published on May 12, 2021

Breaking change in Leads API response

In the source_name format of the Leads response object, the empty string of "" will become "Manually created" for these four endpoints:

• GET /leads
• GET /lead/{id}
• POST /leads
• PATCH /leads/{id}

Due to this change, one more item will be added to the GET /leadSources response: {name: "Manually created"} . The additional response item essentially is not a breaking change, but you might want to look into this in case your code checks the responses in a more strict way.

What is going to change?

Until now, it was not possible to filter manually created leads specifically, because the source_name was an empty string. After adding an actual value to the source_name, it will be possible to filter manually created leads using this value.

Who is affected?

Anyone with functionality built on top of the previous behavior will need to alter their code.

Published on May 6, 2021

Permissions update for CallLogs creation

Endpoint directly affected:

• POST /callLogs

What is going to change?

Going forward, the creation of a call log will be limited by the creating User's permissions. If the User creating the call log does not have the permission to view the Person, Organization or Deal that is attached to this activity, then the call log will not be created. A User can only attach entities they have permissions to see to the call log.

Who is affected?

Anyone with functionality built on top of the previous behaviour might need to alter their code. Therefore, if you are creating call logs then you need to review whether this functionality of the permissions update requires changes on your side.

Published on April 29, 2021

Bug fix in Webhooks payload

We will fix the requests’ payload mismatch for webhooks triggered manually and via the API: the address-related data in the current and previous objects will match the API response format.

Please remove any dependencies relying on the current behavior.

Published on April 28, 2021

Change in the availability of webhooks for apps

What is changing?

Apps that are creating, fetching, and deleting webhooks as a part of their functionality will start to only be able to see and delete webhooks that the app itself has created. This means that starting from the change date, an app can see and delete only webhooks that have the type set as type='application'.

This is done to protect and maintain a separation of admin privileges to manage users' webhooks and applications' webhooks.

Who is affected?

Every app that has functionality that relies on receiving any other type of webhooks besides 'application', e.g. 'general'.

Published on April 5, 2021

Update to the removal of the /*/find, /searchResults, and /searchResults/field endpoints

In April last year we announced the deprecation and removal of the following 6 endpoints:

• GET /deals/find - Searches all deals by their title
• GET /persons/find - Searches all persons by their name
• GET /organizations/find - Searches all organizations by their name
• GET /products/find - Returns data about the products that were found.
• GET /searchResults - Searches all items or 1 item by all fields
• GET /searchResults/field - searches 1 item type by 1 field

Based on the amount of requests we’re still receiving against the deprecated endpoints listed above, the original removal date at March 31, 2021 will be postponed to September 30, 2021.

Continue reading the original announcement to learn more about the new Search API endpoints we suggest you to migrate to.

Who is affected?

Anyone depending on the previously listed 6 deprecated endpoints in any way is affected. In case you are using the previously listed 6 deprecated API endpoints in your code or 3rd party app/integration, please remove any dependency on these endpoints as soon as possible, or by September 30, 2021 the latest. For additional help, check out the new search API migration guide.

Published on March 31, 2021

Replacing the note field in Leads API with fields in Notes API

What is going to change?

We will remove the note field from the following Leads API endpoints:

• GET /leads
• GET /leads/{id}
• POST /leads
• PATCH /leads/{id}

And add lead_id and pinned_to_lead_flag fields to GET /notes endpoint.

Why is it going to change?

Until recently, we only supported having a single note for a Lead. Now we are adding support for multiple Notes. In doing so, it requires to stop using the note property on a Lead (which is in 1:1 relation) and start using the Note entity. The Note entity can be then linked to a Lead and thus it will be in a 1:N Lead to Note relation.

Until the grace time is over, we will create a Note object every time someone calls POST /leads with a note parameter. We will return and update the FIRST Note linked to a Lead on a GET and PATCH call. Therefore when using our API before the grace time is over, the only change will be that in the background a Note object will be created.

The note field will be removed on April 23, 2021. The support for multiple Notes is effective immediately.

Published on March 23, 2021

11 Deals endpoints to return two new fields

We have added two new fields to the responses of the following endpoints:

• GET /deals
• POST /deals
• GET /deals/{id}
• PUT /deals/{id}
• PUT /deals/{id}/merge
• POST /deals/{id}/duplicate
• GET /organizations/{id}/deals
• GET /persons/{id}/deals
• GET /pipelines/{id}/deals
• GET /products/{id}/deals
• GET /stages/{id}/deals

The possible value of the two new fields group_id and group_name can both be null or

• an integer representing the group for group_id
• a string representing the group for group_name

These two fields are read_only and cannot be updated via Deals endpoints.

Published on March 18, 2021

Change in value types for Radio and Checkbox Group Blocks in Embedded app actions

The Radio Group Block and Checkbox Group Block of Embedded app actions will continue to support only string type for the value option in both Block level and items level.

Published on March 10, 2021

Restoration of the Subscription API

Regarding the recent Subscription API update, after further user testing, our product team has found an alternative way to meet the needs of our customers around tracking and predicting the sales revenue. Thus, the Recurring Revenue and Payment Schedules functionalities along with the Subscriptions API endpoints will not be removed and will remain as the foundation of Pipedrive's revenue forecasting and tracking.

A related change to Subscriptions API announced on February 11, 2021 will not be reverted and will continue providing additional linking possibilities between Deals and Recurring Revenue feature.

Published on March 8, 2021

New parameter in PUT /mailbox/mailThreads/{id} endpoint

We have added a new parameter lead_id to the PUT /mailbox/mailThreads/{id} endpoint. This parameter allows an email to be associated together with an existing lead.

Possible values for the parameter are the lead’s unique ID which references the lead, e.g. dc775b7e-db49-444c-8a53-7ee785af1091 or null.

Published on March 1, 2021

New parameter in POST /callLogs endpoint

We have added a new parameter note to the POST /callLogs endpoint. The note parameter allows you to add notes to call logs.

Published on February 18, 2021

Removal of a static field from Users API response

What is going to change?

We will remove the field activated from the responses of the following Users API endpoints:

• GET /users
• POST /users
• GET /users/find
• GET /users/me
• GET /users/{id}
• PUT /users/{id}

Why is it going to change?

We are removing the activated field from these endpoints because the value of the field is static - it is always set to true.

Published on February 16, 2021

Introducing new app extensions - Embedded app actions

Embedded app actions are a new type of app extensions that allow apps to provide a way for users to complete actions right inside Pipedrive without them being redirected. These types of app extensions enable users to, for example, add contacts to email campaigns, send SMS messages, change the status of a document, create tasks in project management tools, etc., without leaving Pipedrive.

Embedded actions work by opening a modal window that can be customized with different Blocks and Action buttons. It can handle various types of user interactions, allowing to apply business and validation rules.

To start developing Embedded app actions, see our guides on the overview of Embedded app actions, Component library, and User interaction handling.

Published on February 15, 2021

New field in Deals object

What is going to change?

A new field renewal_type will be added to the Deals object. This change affects all Deals endpoints which return the Deal object(s) in the response.

The possible values for the renewal_type field are one_time, renewal, and new_business.

• one_time - Deal is a one-time transaction, no repetition of business transactions is expected.
• renewal - the Deal is a new relationship with a new client. Such Deals will have renewals to prolong terms of agreement with customers. This Deal is a base/parent Deal for a group of Deals which will be the future renewals.
• new_business - the Deal is connected to the new business type of a Deal via a Deal group and is used by account management or customer success teams to keep track of upcoming prolongation of business relationships.

For example, to renew the Deal only once, add the following:

{
   ...
   "renewal_type": "one_time",
   ...
}

Why is it going to change?

This change is linked to our previous announcement about substituting the Recurring Revenue and Payment Schedule features with an up-and-coming feature called Renewal management. In order to make it work, we need to add a new Deals field renewal_type.

Published on February 11, 2021

Removal of the Subscriptions API

We have now deprecated and will soon be removing the following nine Subscriptions API endpoints:

• GET /subscriptions/{id}
• GET /subscriptions/find/{dealId}
• GET /subscriptions/{id}/payments
• POST /subscriptions/recurring
• POST /subscriptions/installment
• PUT /subscriptions/recurring/{id}
• PUT /subscriptions/installment/{id}
• PUT /subscriptions/recurring/{id}/cancel}
• DELETE /subscriptions/{id}

What's going to change?

The Recurring Revenue and Payment Schedule features will be substituted with a new renewal deals functionality and therefore the previously mentioned features will no longer be available as a standalone functionality.

Why?

We wish to deliver the best possible sales oriented approach. Having that in mind, we need to move the functionalities of the Recurring Revenue and the Payment Schedules closer to Deals and Pipeline processes to truly support sales success of Pipedrive users.

Published on February 4, 2021

Change in behavior of 4 bulk DELETE endpoints

What will change?

Four Pipedrive API bulk DELETE endpoints will be limited to deleting up to 1000 items per request.

The requests made against the following four bulk DELETE endpoints will be serviced slower than before. The processing speed will be based on the number of items being deleted and the worst case scenario being at most 20 seconds for a request with 1000 items.

The change affects the following four API endpoints:

• DELETE /activities
• DELETE /deals
• DELETE /organizations
• DELETE /persons

Why?

We are making technical improvements in the backend to increase the reliability of features reacting to changes made to entities. Examples of those features include Workflow Automation and Webhooks. In the current state, in rare cases when performing large bulk deletes, a reaction could be lost.

The bulk deletes will be done asynchronously in the background by going through items 1 by 1. This will make it possible for all related features to react to changes in a reliable way.

Who is affected?

Anyone depending on the behavior of those previously listed four endpoints in any way is affected. In case you are using the four endpoints in your code or 3rd party app/integration, please make sure that you complete the following two steps as soon as possible (or by March 1, 2021 the latest):

• send the maximum of 1000 items at once
• your code can handle the requests taking longer to finish

Published on January 29, 2021

companydomain to replace api-proxy in API requests

What?

From now on, we’re suggesting you to use https://companydomain.pipedrive.com/api/v1/ API domains for making requests to Pipedrive API. Read more about Pipedrive API URL naming convention here.

Why?

This suggestion comes in addition to the change announced on Feb 21 last year when we introduced a new parameter api_domain in OAuth 2.0 /oauth/token responses for our external developers to receive up-to-date company_domain and api_domain every time one makes the initial request to get the tokens or when one refreshes a token. Also, using the companydomain prefix should make your requests to our API faster.

Published on January 27, 2021

New parameters in App actions' URLs

App actions triggered from the Activity list view will now have additional parameters activity_type, activity_start_date and activity_end_date added to the URL of the action to describe a filter that has been applied to the selected activities. These parameters will be included in the filter parameter.

The activity_type parameter will always be included in the URL for actions from the Activity list view, activity_start_date and activity_end_date will be added only when they are selected by the user.

For more information, see App actions' guide.

Published on January 15, 2021

Updates to Goals API

We’re introducing three updates to our Goals API:

1. There’s a new goal type - revenue_forecast. This type of goal allows users to track their revenue forecast.

2. Goals don’t need to have an end date. You can set up infinite, open-ended goals by setting end to null.

3. report_ids array is now a part of the response of the Goals API. This array includes IDs of reports used in the Insights feature to highlight the goal’s progress over time. Every goal should have at least one report attached to it.

Published on January 12, 2021

Phone calls integration OAuth scope

CallLogs endpoints have now been added to a new scope Phone calls integration which is available for OAuth apps. The scope will allow apps to enable advanced call integration features like logging call duration and other metadata and play call recordings inside Pipedrive.

You can find the following endpoints of the CallLogs resource under this scope:

• POST /callLogs
• DELETE /callLogs/{id}
• POST /callLogs/{id}/recordings
• GET /callLogs
• GET /callLogs/{id}

You can read more about the scopes and permission explanations here.

Published on January 7, 2021

GET/itemSearch now supports returning Leads

What will change?

GET /itemSearch now supports returning Leads in related_items for Organizations and Persons that are linked to it. When the search_for_related_itemsfor GET /itemSearch is set to true, the response will include up to 100 newest related Leads in addition to up to a 100 Deals for each found Person and Organization.

Published on January 6, 2021

Breaking change in GET /files endpoint

What will change?

We are going to change the definition of the sort parameter of GET /files endpoint. We’re going to allow sorting by 2 columns only (id, update_time) and restrict sorting by more than 1 column at the same time (e.g. field_name_1 ASC, field_name_2 DESC won’t work anymore).

Why?

We are optimising our sorting operations together with moving to a new service for files management.

Who is affected?

Anyone doing queries to GET /files using sorting by file_type.

Published on December 17, 2020

Bug fix in date and datetime fields

There was an issue with date and datetime fields, which affected Deals, Persons, Organizations, Products and Activities resources. When filtering by date and/or datetime with the operators <, >, <=, >= it might have returned rows with an empty date (0000-00-00) and/or empty datetime (0000-00-00 00:00:00). We made the server response more strict, which means that now when filtering the same way the rows with empty date will always be excluded.

The issue has now been fixed.

Please let us know if you have any questions by replying to the forum thread here.

Published on December 11, 2020

Removal of two endpoints from the /Users resource

We have now deprecated and will be removing the following two endpoints from the Users resource:

• GET /users/{id}/blacklistedEmails
• POST /users/{id}/blacklistedEmails

In case you are still using the above-mentioned API endpoints in your code or 3rd party app/integration, please remove any dependency on these endpoints by December 28, 2020.

Published on November 23, 2020

Leads OAuth scopes

Leads endpoints have now been added to two new scopes which are available for OAuth apps.

You can find the endpoints of the Leads resource under leads:read and leads:full scopes.

Endpoints in leads:full scope:

• POST /leads
• GET /leads
• GET /leads/{id}
• PATCH /leads/{id}
• DELETE /leads/{id}
• GET /leadSources
• POST /leadLabels
• GET /leadLabels
• PATCH /leadLabels/{id}
• DELETE /leadLabels/{id}

Endpoints in leads:read scope:

• GET /leads
• GET /leads/{id}
• GET /leadSources
• GET /leadLabels

You can read more about the scopes and permission explanations here.

Published on October 30, 2020

New logic for updating scopes on existing apps

Apps can now update their OAuth scopes without automatically having the app uninstalled for all existing users.

The process will now work as follows:

Apps (draft/private, unlisted and public) can update their scopes at any time.

When the scopes have been updated, existing users will receive a notification email letting them know of the change in scopes and asking them to reauthorize the app.

Apps that decide to update their scopes must be able to clearly direct users to reauthorize the app in the Marketplace. This must be done to allow users to use the app in its full capacity. The scopes change will not halt the app's functionality - the features built with previous scopes will continue working.

From the Marketplace side, the app listing will remain available and won’t be sent back into the app approval process. The scopes displayed in the installation screen of the app listing will be automatically updated to reflect the new scopes.

Published on October 30, 2020

Bug fix in GET /pipelines endpoint

There were two issues with GET /pipelines endpoint. It ignored start and limit parameters when getting all pipelines, and in some cases for the more_items_in_collection field an incorrect value was returned (true instead of false).

Both issues have now been fixed.

Please let us know if you have any questions by replying to the forum thread here.

Published on October 27, 2020

Closing of GET /leadLabels/:id endpoint

We are closing a non-functional GET /leadLabels/:id endpoint for fetching one Lead label at a time, due to it not being fully implemented.

Published on October 20, 2020

Breaking change in POST /deals and PUT /deals/{id} endpoints

Endpoints directly affected:

• POST /deals
• PUT /deals/{id}

What will change?

In Pipedrive, admin users can set visibility groups and permission sets. Visibility groups are used to categorize users and dictate what entity they will be allowed to see. Permission sets dictate what actions the users in the account are able to perform. To see and set the visibility group of the entity through the API we have the visible_to parameter.

If one tries to set the wrong visible_to value when requesting POST /organizations, PUT /organizations/{id}, POST /persons or PUT /persons/{id} endpoints, they will get the 403 response code. We’re adding that same additional validation to POST /deals and PUT /deals/{id} endpoints.

Why?

POST /deals and PUT /deals/{id} endpoints don't currently return an error if an incorrect value is given to visible_to parameter, instead the request is shown to be successful and it will ignore the data sent by the user.

Who is affected?

This change affects only non-admin type of users who belong to a permission set where the permission Can change visibility of items is turned off.

Published on October 13, 2020

Breaking change in /subscriptions/recurring and /subscriptions/installment endpoints

Endpoints directly affected:

• POST /subscriptions/recurring
• POST /subscriptions/installment

What will change?

Instead of allowing to specify any random 3 character string as currency, the service will start checking if the specified currency is a real currency or a custom currency used in a company. Also, the service will start returning the error Unknown currency provided! if the inserted currency is unknown.

You can use GET /currencies endpoint to see a list of currencies accepted by Pipedrive as well as custom currencies a company might have created.

Why?

Users are able to use the “incorrect” currencies as parameters and it may cause issues.

Who is affected?

Anyone with functionality built on top of the previous behaviour might need to alter their code.

Published on October 6, 2020

New endpoints in products:full scope

Products:full scope now allows apps to have access to 2 new endpoints.

By selecting the products:full scope, an app can now have access to the 2 following endpoints, which allow the app to add or remove followers from products:

• POST /products/{id}/followers
• DELETE /products/{id}/followers/{id}

You can read more about the scopes and permission explanations here.

Published on September 21, 2020

Fix in POST /subscriptions/recurring endpoint documentation

We had the payments parameter marked as required in the documentation of POST /subscriptions/recurring endpoint in our API Reference, but under the hood it is not a required parameter. We have now removed the required flag (a red asterisk) from the payments parameter.

Published on September 21, 2020

New parameter in two Deals endpoints

We have added a new parameter expected_close_date to the PUT /deals/{id} and POST /deals endpoints.

The expected_close_date parameter allows you to change the date of when the Deal is expected to be marked as won.

Published on August 7, 2020

Introducing Subscriptions API

We have added a brand new Subscriptions resource to our API which represents the Recurring Revenue feature inside Pipedrive.

Subscriptions represent the revenue that is occurring over time with payments either in set or varying amounts. Subscriptions have two types - installment and recurring. Installment Subscription occurs over time with payments in varying amounts and payment dates. Recurring Subscription occurs over fixed intervals of time with payments of the same amount.

The Subscriptions resource includes the following endpoints:

• GET /subscriptions/{id}
• GET /subscriptions/find/{dealId}
• GET /subscriptions/{id}/payments
• POST /subscriptions/recurring
• POST /subscriptions/installment
• PUT /subscriptions/recurring/{id}
• PUT /subscriptions/installment/{id}
• PUT /subscriptions/recurring/{id}/cancel
• DELETE /subscriptions/{id}

To be able to use an endpoint using OAuth authorization, the endpoint needs to be added to a scope. We have added the endpoints of the Subscriptions resource to our deals:read and deals:full scopes. You can read more about the scopes and permission explanations here.

Published on August 6, 2020

Introducing Leads API

We have added a brand new Leads resource to our Pipedrive API.

In the sales world, Leads are potential Deals that are stored separately in the Leads Inbox within Pipedrive.

The Leads resource allows you to get, create, update and delete Leads, Lead Labels and get Lead Sources.

In API requests, each Lead needs to be named (using the title field) and be linked to either a Person or an Organization. Linking to either a Person or an Organization is required in order to keep all the information regarding Contacts in one part of Pipedrive, instead of separating it between Contacts and Leads Inbox, as it is crucial information in sales peoples' daily work. This way all the communication between the sales person and the contact can be found in one place (Person or Organization detail view in Pipedrive) through the entire sales cycle.

Leads can contain the same custom fields as the custom fields of a Deal. If the value of a custom field has been set for a Lead, it will appear in the response of the request.

The Leads resource includes the following endpoints:

• GET /leads
• GET /leads/{id}
• GET /leadLabels
• GET /leadLabels/{id}
• GET /leadSources
• POST /leads
• POST /leadLabels
• DELETE /leads/{id}
• DELETE /leadLabels/{id}
• PATCH /leads/{id}
• PATCH /leadLabels/{id}

POST and PATCH requests made to the Leads endpoints must be done using content-type: application/json.

Please note that the OAuth scope is currently not available for the Leads endpoints, but we are working to get it added.

Published on July 23, 2020

Improved protection of user data

We have now improved the security of user data.

What has changed?

When returning the User object, the following API endpoints

• GET /users
• GET /users/{id}
• POST /users
• PUT /users/{id}

will have all fields except for id, name and email set to null if the user is unverified in the company (which is always the case for the POST /users endpoint).

This also affects endpoints of other entities such as Deals, Persons, Organizations, Notes, etc., which may contain related User objects.

Who is affected?

Anyone with functionality built on top of the previous behaviour, for example: anyone who strictly relies on the values in the response of the aforementioned endpoints and related webhooks.

The list of affected fields in User endpoints:

• phone: string
• created: string (date)
• modified: string (date)
• default_currency: string
• locale: string
• lang: int
• timezone_name: string
• timezone_offset: string
• signup_flow_variation: string
• icon_url: string

The field lang will return the default value of 1.

Published on July 14, 2020

Removal of additional_data and pagination objects from 3 endpoints

What will change?

We have now deprecated and will be removing the additional_data and pagination objects on July 1, 2020 from the responses of the following Deal, Person and Organization endpoints.

Here is the list of 3 affected endpoints:

How the response body currently looks:

{
  "success": true,
  "data": [
    007
  ],
  "additional_data": {
    "pagination": {
      "start": 0,
      "limit": 1,
      "more_items_in_collection": false
    }
  }
}

Response body after the change:

{
  "success": true,
  "data": [
    007
  ]
}

If your requests to those three endpoints also contain pagination related parameters limit and start we recommend removing those as they won’t serve their purpose any longer.

Who is affected?

Anyone with functionality built on top of the previous behaviour. For example, anyone who is strictly checking the shape of the response of the aforementioned 3 endpoints.

Published on May 25, 2020

New scopes for Goals and Teams

Goals help sales teams meet their sales targets and Teams allow sales people to form groups of users within the organization for more efficient management.

To be able to use an endpoint using OAuth authorization, the endpoint needs to be added to a scope. This is why we have added the endpoints of the Goals and Teams resources to our scopes.

You can find the endpoints of the Goals resource under goals:read and goals:full scopes, and the endpoints of the Teams resources under users:read and admin scopes.

You can read more about the scopes and permission explanations here.

Published on April 23, 2020

New parameters added to /activities POST and PUT endpoints

We have added four new parameters to POST /activities and PUT /activities/{id} endpoints:

Published on April 15, 2020

Removal of the /*/find, /searchResults, and /searchResults/field endpoints, replaced by 6 new endpoints

What will change?

We have now deprecated and will soon be removing the following 6 API endpoints:

Why?

We are introducing 6 new endpoints:

The new Search API endpoints offer extended functionality over the old search API and have a unified future-proof response format. The extended functionality allows you to do complicated queries from several item types and fields at once.

For example you can use /v1/itemSearch?item_types=deal,person&fields=title,name,custom_fields&term=example to search from all persons and deals by the person’s name, deal title and both items custom fields and order them by relevance.

The /*/search endpoints are aliases for /v1/itemSearch?item_types=* endpoint with narrower OAuth2 scopes for if you are a marketplace app owner and would like your app to only have read access to specific item types instead of the full search scope.

Who is affected?

Anyone depending on the previously listed 6 deprecated endpoints in any way is affected. In case you are using the previously listed 6 deprecated API endpoints in your code or 3rd party app/integration, please remove any dependency on these endpoints as soon as possible, or by March 31, 2021 the latest. For additional help, check out new search API migration guide.

Published on April 8, 2020

Removal of the reference_activities_count field

What will change?

We have now deprecated and will be removing the reference_activities_count field on May 31, 2020 from

• the responses of the following Deal, Person and Organization endpoints
• the Deal, Person, and Organization related webhook payloads

Here is the list of 21 affected endpoints:

There will be no changes to any request body.

Why?

We are no longer updating that field. Until removal, the value of the field will always be 0:

"reference_activities_count": 0

Who is affected?

Anyone with functionality built on top of the previous behaviour, for example, anyone who is strictly checking the shape of the response of the 21 endpoints and related webhooks.

Published on March 31, 2020

New parameters added to flow endpoints

We have added new parameters all_changes and items to the following endpoints:

• GET /deals/{id}/flow
• GET /organizations/{id}/flow
• GET /persons/{id}/flow

The all_changes parameter allows you to choose whether to show custom field updates or not. The items parameter is a comma-separated string for filtering out item-specific updates.

Published on March 26, 2020

New field added to custom field POST endpoints

We have added a new address field to the following endpoints:

• POST /dealFields
• POST /organizationFields
• POST /personFields
• POST /productFields

The address field is used to store addresses. You can read more about the types of custom fields here.

Published on March 24, 2020

New fields in Users GET /users/me endpoint

We have added two new fields to the GET /users/me endpoint. When getting the current user data, the output now contains the following fields:

• company_country
• company_industry

You can now see how the output will look like in the getting user data page.

Published on March 4, 2020

New parameter in OAuth /oauth/token responses

What will change?

We have added a new parameter api_domain to OAuth /oauth/token responses.

For now, only the apps created on or after February 20, 2020 will see a new parameter in the OAuth /oauth/token response.

On June 1, 2020, the code will automatically start sending the new parameter to all requests, i.e. apps created before February 20, 2020 will also start seeing the new parameter in the OAuth /oauth/token response. If you are strictly checking the shape of the response, please update your code to take the new parameter into account.

Why?

Until now (and because we ask you to use https://companydomain.pipedrive.com domains for making API requests), in order to find out the company_domain, you had to get the OAuth tokens first, make a request to /users/me endpoint and store it on your side. Also, the company_domain can change so you had to make additional request to /users/me every once in a while.

But with this change you do not have to do that anymore, because you will now receive up-to-date company_domain every time you make the initial request to get the tokens or when you refresh a token.

The current response:

{
    "access_token": "53:179:6317ef33a9fb0c4d604ce0695dad44a12bad44c9",
    "token_type": "Bearer",
    "expires_in": 3599,
    "refresh_token": "53:179:5de81994d77491d22bc10eab3bc0810f84864297",
    "scope": "base,deals:full,contacts:read"
}

The new response with the added api_domain parameter:

{
    "access_token": "53:179:6317ef33a9fb0c4d604ce0695dad44a12bad44c9",
    "token_type": "Bearer",
    "expires_in": 3599,
    "refresh_token": "53:179:5de81994d77491d22bc10eab3bc0810f84864297",
    "scope": "base,deals:full,contacts:read",
    "api_domain": "https://mycompanydomain.pipedrive.com"
}

Who is affected?

Any app created before February 20, 2020 with functionality built on top of the previous behavior need to alter their code by June 1, 2020.

Any apps created on or after February 20, 2020 will already see the new parameter in the OAuth /oauth/token/ response and do not need to alter anything concerning this change.

Published on February 21, 2020

New Teams resource

We have added a brand new Teams resource. Teams allow sales people to form groups of users within the organization for more efficient management.

The new Teams resource includes the following endpoints:

Published on December 10, 2019

New Goals resource

We have added a brand new Goals resource. Goals help sales teams meet their sales targets.

The new Goals resource includes the following endpoints:

Published on November 29, 2019

New parameter in Notes POST and PUT endpoints

We have added a new parameter user_id to the POST /notes and PUT /notes/{id} endpoints.

By inserting the ID of a user into the user_id parameter when making requests against the following endpoints, you can now choose or change the author of a note:

• POST /notes
• PUT /notes/{id}

For example, this user_id parameter might come in handy when importing data to Pipedrive. Please keep in mind that only an admin can change the author.

Published on October 17, 2019

Breaking change in /searchResults and /organizations/find endpoints

Endpoints directly affected:

• GET /searchResults
• GET /organizations/find

What will change?

When the /searchResults and /organizations/find endpoints return an organization with no details, the organization details field will return an empty object {} instead of an empty string "".

Why?

This change will make endpoint responses more consistent by forcing the returned organization details field to always be an object.

The responses will be more consistent with results that do have organization details, which currently have the following format:

{
    "org_address": "organization's address"
}

Who is affected?

Any integration with functionality built on top of the previous behavior might need to alter their code.

Published on September 23, 2019

Removal of access_level feature

We have chosen to delete the access_level feature due to it being an older and not fully implemented feature.

It was previously available in the following endpoints under Roles:

• GET /roles/{id}/settings
• POST /roles/{id}/settings
• GET /roles/{id}

And there was a possibility to change it separately under Deal, Organization, Person, Product:

• GET /deals/{id}/permittedUsers
• GET /organizations/{id}/permittedUsers
• GET /persons/{id}/permittedUsers
• GET /products/{id}/permittedUsers

Published on September 17, 2019

Bugfix in /activities endpoint

/activities endpoint:

Additional information about pagination will now return correct values for the more_items_in_collection when the related_objects=0 parameter is passed with the request.

Published on September 3, 2019

Breaking change in the JSON response structure of the Delete Person webhook

What?

We will be introducing a breaking change in the JSON response structure of the Delete Person webhook.

Currently the data for a Delete Person webhook is incomplete. For example, if a user has saved more than one email/phone nr on a Contact, then only the primary email/phone nr. will appear in the webhook data. Because of this, we will change the property type from a string to an array and add additional values (e.g. secondary email/phone nr) into the array when they are present.

When?

Changes will go live on October 23, 2019.

Why?

If our customers remove a Person, they can then use webhook data to delete the same information on their end. We would like to make sure when information is removed from Pipedrive, it can also be seamlessly removed from our customers’ databases.

Who is affected?

Anyone who has set up a webhook for a Person Delete event. If you or your team has built functionality on top of a previous response structure, then please make sure your code is changed accordingly.

Published on August 23, 2019

Websocket functionality deprecation

We are going to deprecate the websocket usage in client-nodejs for third-party developers https://github.com/pipedrive/client-nodejs/pull/94.

The current library will stop working on September 24, 2019. In case of any dependency affected by this deprecation, please keep in mind this is a breaking change. It is very urgent for you to update your library and migrate to using webhooks.

Published on July 30, 2019

Change in how future Activities behave

Endpoints directly affected:

• PUT /activities/{id}
• GET /activities

What will change?

Currently, if future activities (due_date and due_time in the future) have been marked as done, those activities’ due_date and due_time have been overwritten with the marked_as_done_time. This behaviour will be changed. Starting from August 15, the due_date and due_time will remain as they were initially set, different from the marked_as_done_time.

Why?

We are working on improving Pipedrive’s integrations with external calendars and this is a necessary change. Overall, this was an unexpected behaviour and we are bringing it into line with how calendars usually behave.

Who is affected?

Anyone creating statistics based on activities.
Anyone marking future activities as done.

If there is functionality built on top of the previous behaviour, it will have to be altered.

Published on July 15, 2019

Breaking change in PUT /activities/{id} endpoint

There will be a breaking change for the PUT /activities/{id} endpoint.

Starting July 5th, in order to reconcile with other item PUT endpoints of our API, the endpoint will start directing to the DELETE /activities/{id} endpoint when performing a soft delete by changing active_flag: 0.

Published on June 25, 2019

Akamai WAP implementation

In order to provide a more secure service to our customers, Pipedrive is in the process of implementing Akamai WAP (Web Application Protector). The implementation of this tool ensures that malicious requests will be blocked.

Why are we telling you this?

In the implementation phase we are eliminating all false positives from the system to ensure that legitimate requests will not be blocked. If you happen to notice that your request is blocked and receives 403 error, please contact us and we can investigate why this occurred.

Published on June 17, 2019

New endpoint in Filters resource

We have added a new GET /filters/helpers endpoint to the Filters resource.

The new endpoint allows you to see the all the possible operators and their meanings for creating conditions in order to either add or update a Filter. Here is a tutorial showing how to add a new Filter using the GET /filters/helpers endpoint.

Published on June 4, 2019

New endpoint in Deals resource

We have added a new GET /deals/summary endpoint to Deals resource.

The new endpoint allows you to see the summary of all the Deals in one company. You can customize the response of the summary with the following parameters: status, filter_id, user_id, stage_id. Here is an example of one company's Deals summary without specifying any parameters:

{
  "success": true,
  "data": {
    "values_total": {
      "USD": {
        "value": 201.99,
        "count": 91,
        "value_converted": 201.99,
        "value_formatted": "201,99 $",
        "value_converted_formatted": "201,99 $"
      }
    },
    "weighted_values_total": {
      "USD": {
        "value": 201.99,
        "count": 91,
        "value_formatted": "201,99 $"
      }
    },
    "total_count": 91,
    "total_currency_converted_value": 201.99,
    "total_weighted_currency_converted_value": 201.99,
    "total_currency_converted_value_formatted": "201,99 $",
    "total_weighted_currency_converted_value_formatted": "201,99 $"
  }
}

Published on May 30, 2019

Daily API limit for POST/PUT endpoints

We're introducing a daily API fair usage limit for POST/PUT endpoints. We consider fair usage to be a maximum of 10 000 POST/PUT requests daily per user per 24 hours. The daily limit will be reset at midnight in UTC.

In the case of exceeding the 10 000 daily limit on multiple occasions, we may start blocking your POST/PUT requests towards our API.

The daily limit is introduced in addition to the rate limiting and will apply to all POST/PUT endpoints provided by our API.

The daily fair usage limit of 10 000 POST/PUT requests will be the same for all three plans (Silver, Gold, Platinum).

Introducing the daily API limit allows us to protect the system from data overload, to have more equal and higher performance distribution in order to handle your requests quicker.

Published on May 24, 2019

Additional change in email and phone number quantity limit

What will change?
The number of emails and phone numbers a user can add to a person object will be limited to 50 records each. A user can add a maximum of 50 emails and a maximum of 50 phone numbers per person.

When a person object has reached 50 emails or 50 phone numbers, the UI will no longer show the “+ add more” button for this person. If a 3rd party developer sends more than 50 emails or phone numbers, they will receive an API error. This API error should help to prevent data loss for the customer.

Why?
This change comes in addition to the change announced on May 7th as 3rd party developers can still unknowingly abuse the API - for example, adding thousands of emails and/or phone numbers into one person. This happens regularly a few times per month and it adds a lot of real-time processing demands to our servers, causing slow webapp performance for all the companies that share the same server.

Published on May 17, 2019

Adding a deal bug fix

We identified an issue with POST /deals endpoint. It was possible to add last_activity_date and next_activity_date fields when adding a deal.

This has been fixed, because these are values which will automatically be calculated based on the activities linked to the deal.

Please let us know if you have any questions by replying to the forum thread here.

Published on May 17, 2019

New limit for importing emails and phone numbers

What will change?
The number of emails and phone numbers a user can add to a “person” type object will be limited to 150 records each. A user can add a maximum of 150 emails and a maximum of 150 phone numbers per person.

When a person object has reached 150 emails, their UI will no longer show the “+ add more” button. If a 3rd party developer sends more than 150 emails, they will receive an API error. This API error should help to prevent data loss for the customer.

Why?
3rd party developers can unknowingly abuse the API - for example, adding thousands of emails and/or phone numbers into one person happens regularly a few times per month. They usually clean up after themselves, but this still adds a lot of real-time processing demands to our servers.

Who is affected?
The most obvious will be companies who already have too many emails or phone numbers per person, as they will no longer be able to add any more emails or phone numbers to their “person” type objects.

Published on May 7, 2019

related_objects in API response can now be turned off

We have added a new global GET parameter related_objects=0 that will turn off related_objects in API response. We have added it to boost performance and improve response time for the data you really need.

Published on April 22, 2019

Removal of the /users/{id}/activities endpoint of the Users resource

We will be removing the following endpoint from the Users resource:

• GET/users/{id}/activities

This endpoint was deprecated 1.5 years ago. In case you are still using the above-mentioned API endpoint in your code or 3rd party app/integration, please remove any dependency on this endpoint.

You have the option to replace it by using GET /activities endpoint by passing the user_id parameter. You will get the same exact response with the addition of related_objects being added to the output.

Published on April 9, 2019

New size limit for notes

We will be decreasing the size limit for notes. There will be no need to edit existing notes, but after April 14th it will not be possible to create notes larger than 3MB.

We decided to decrease the note size to approximately 3,000,000 characters (or 3MB per note) because large-sized notes reduce application memory and affect the performance negatively.

If your code or 3rd party app/integration has been designed to create or update notes, please doublecheck these as they may fail if the note being created or updated is too large.

Published on March 19, 2019

Removal of the /authorizations endpoint

We will be removing the Authorizations endpoint:

• POST /authorizations

We deprecated this endpoint on February 28, 2019, and we strongly advise you to avoid the use of this endpoint. The /authorizations endpoint is a legacy way of authorization using generic API keys. Such an approach does not provide transparency into which applications have access to data nor the opportunity to control the permissions these integrations have. Therefore we suggest using OAuth Authorization instead.

In case you are using the /authorizations API endpoint in your code or 3rd party app/integration, please remove any dependency on this endpoint as soon as possible.