Every time you create an app for the Pipedrive Marketplace, you'll need to determine what kind of user-related data you need access to. We use scopes for that.
Scopes are used to limiting an app's access to user-related data and they'll let you specify exactly what kind of access you need.
On the other hand, it's also important for the user to know exactly what the app can and cannot do with the data in their Pipedrive account. Once a user permits access to their data, each scope will define the endpoints the app has access to.
The user has the option to either accept or deny all scopes. Because of this, it's a good idea to build apps that only request scopes that are absolutely necessary for your particular use-case.
If you need to change the scopes of an already existing app, be sure to read more about how it can affect your app's users here.
Here's our mapping of API endpoints to access scopes:
base
Access to basic information
Read the settings of the authorized user and currencies in an account.
This is the default permission that is always enabled for all apps.
"base": [
"GET /users/me"
"GET /userConnections",
"GET /userSettings",
"GET /currencies"
]
deals:read
Deals: Read only
Read most of the data about deals and related entities - deal fields, products, followers, participants; all notes, files, filters, pipelines, stages, and statistics. Does not include access to activities (except the last and next activity related to a deal).
"deals:read": [
"GET /deals/find",
"GET /deals/search",
"GET /deals/timeline",
"GET /deals/{id}",
"GET /deals",
"GET /dealFields",
"GET /dealFields/{id}",
"GET /deals/{id}/files",
"GET /persons/{id}/deals",
"GET /pipelines/{id}/deals",
"GET /pipelines/{id}/conversion_statistics",
"GET /pipelines/{id}/movement_statistics",
"GET /products/{id}/deals",
"GET /notes",
"GET /notes/{id}",
"GET /noteFields",
"GET /deals/{id}/followers",
"GET /files",
"GET /files/{id}",
"GET /files/{id}/download",
"GET /deals/{id}/participants",
"GET /stages",
"GET /stages/{id}",
"GET /stages/{id}/deals",
"GET /pipelines",
"GET /pipelines/{id}",
"GET /filters",
"GET /filters/{id}",
"GET /organizations/{id}/deals",
"GET /deals/summary",
"GET /subscriptions/{id}",
"GET /subscriptions/find/{id}",
"GET /subscriptions/{id}/payments"
]
deals:full
Deals: Full access
Create, read, update and delete deals, its participants and followers; all files, notes, and filters. It also includes read access to deal fields, pipelines, stages, and statistics. Does not include access to activities (except the last and next activity related to a deal).
"deals:full": [
"POST /deals",
"POST /deals/{id}/duplicate",
"PUT /deals/{id}",
"PUT /deals/{id}/merge",
"DELETE /deals/{id}",
"DELETE /deals",
"POST /files/remote",
"POST /files/remoteLink",
"POST /deals/{id}/followers",
"POST /deals/{id}/products",
"DELETE /deals/{id}/products/{product_attachment_id}",
"POST /notes",
"PUT /notes/{id}",
"DELETE /notes/{id}",
"POST /files",
"PUT /files/{id}",
"DELETE /files/{id}",
"POST /deals/{id}participants",
"POST /filters",
"PUT /filters/{id}",
"DELETE /filters",
"DELETE /filters/{id}",
"GET /deals/find",
"GET /deals/search",
"GET /deals/timeline",
"GET /deals/{id}",
"GET /deals",
"GET /dealFields",
"GET /dealFields/{id}",
"GET /deals/{id}/files",
"GET /persons/{id}/deals",
"GET /pipelines/{id}/deals",
"GET /pipelines/{id}/conversion_statistics",
"GET /pipelines/{id}/movement_statistics",
"GET /products/{id}/deals",
"GET /notes",
"GET /notes/{id}",
"GET /noteFields",
"GET /deals/{id}/followers",
"GET /files",
"GET /files/{id}",
"GET /files/{id}/download",
"GET /deals/{id}/participants",
"GET /stages",
"GET /stages/{id}",
"GET /stages/{id}/deals",
"GET /pipelines",
"GET /pipelines/{id}",
"GET /filters",
"GET /filters/{id}",
"GET /organizations/{id}/deals",
"GET /subscriptions/{id}",
"GET /subscriptions/find/{id}",
"GET /subscriptions/{id}/payments",
"DELETE /subscriptions/{id}",
"POST /subscriptions/installment",
"POST /subscriptions/recurring",
"PUT /subscriptions/installment/{id}",
"PUT /subscriptions/recurring/{id}",
"PUT /subscriptions/recurring/{id}/cancel",
"DELETE /deals/{id}/followers/{id}",
"DELETE /deals/{id}/participants/{id}"
]
mail:read
Mail: Read only
Read mail threads and messages.
"mail:read": [
"GET /deals/{id}/mailMessages",
"GET /mailbox/mailMessages/{id}",
"GET /mailbox/mailThreads",
"GET /mailbox/mailThreads/{id}",
"GET /mailbox/mailThreads/{id}/mailMessages",
"GET /persons/{id}/mailMessages",
"GET /organizations/{id}/mailMessages"
]
mail:full
Mail: Full access
Read, update and delete mail threads. Also grants read access to mail messages.
"mail:full": [
"PUT /mailbox/mailThreads/{id}",
"DELETE /mailbox/mailThreads/{id}",
"GET /deals/{id}/mailMessages",
"GET /mailbox/mailMessages/{id}",
"GET /mailbox/mailThreads",
"GET /mailbox/mailThreads/{id}",
"GET /mailbox/mailThreads/{id}/mailMessages",
"GET /persons/{id}/mailMessages",
"GET /organizations/{id}/mailMessages"
]
activities:read
Activities: Read only
Read activities, its fields and types; all files and filters.
"activities:read": [
"GET /activities",
"GET /activities/{id}",
"GET /activityFields",
"GET /activityTypes",
"GET /deals/{id}/activities",
"GET /persons/{id}/activities",
"GET /files",
"GET /files/{id}",
"GET /files/{id}/download",
"GET /filters",
"GET /filters/{id}",
"GET /organizations/{id}/activities",
"GET /users/{id}/activities"
]
activities:full
Activities: Full access
Create, read, update and delete activities and all files and filters. Also includes read access to activity fields and types.
"activities:full": [
"POST /activities",
"PUT /activities/{id}",
"DELETE /activities",
"DELETE /activities/{id}",
"POST /files/remote",
"POST /files/remoteLink",
"POST /files",
"PUT /files/{id}",
"DELETE /files/{id}",
"POST /filters",
"PUT /filters/{id}",
"DELETE /filters",
"DELETE /filters/{id}",
"GET /activities",
"GET /activities/{id}",
"GET /activityFields",
"GET /activityTypes",
"GET /deals/{id}/activities",
"GET /persons/{id}/activities",
"GET /files",
"GET /files/{id}",
"GET /files/{id}/download",
"GET /filters",
"GET /filters/{id}",
"GET /organizations/{id}/activities",
"GET /users/{id}/activities"
]
contacts:read
Contacts: Read only
Read the data about persons and organizations, their related fields and followers; also all notes, files, filters.
"contacts:read": [
"GET /deals/{id}/persons",
"GET /persons/find",
"GET /persons/search",
"GET /persons/{id}",
"GET /persons/{id}/files",
"GET /persons",
"GET /personFields",
"GET /personFields/{id}",
"GET /persons/{id}/followers",
"GET /organizationFields",
"GET /organizationFields/{id}",
"GET /organizations/{id}/files",
"GET /organizations/{id}/persons",
"GET /organizations/find",
"GET /organizations/search",
"GET /organizations/{id}",
"GET /organizations",
"GET /organizationRelationships",
"GET /organizationRelationships/{id}",
"GET /organizations/{id}/followers",
"GET /notes",
"GET /notes/{id}",
"GET /noteFields",
"GET /files",
"GET /files/{id}",
"GET /files/{id}/download",
"GET /filters",
"GET /filters/{id}"
]
contacts:full
Contacts: Full access
Create, read, update and delete persons and organizations and their followers; all notes, files, filters. Also grants read access to contacts-related fields.
"contacts:full": [
"POST /persons",
"POST /persons/{id}/picture",
"PUT /persons/{id}",
"PUT /persons/{id}/merge",
"DELETE /persons/{id}",
"DELETE /persons/{id}/picture",
"DELETE /persons",
"POST /persons/{id}/followers",
"POST /files/remote",
"POST /files/remoteLink",
"POST /organizations",
"PUT /organizations/{id}",
"PUT /organizations/{id}/merge",
"DELETE /organizations",
"DELETE /organizations/{id}",
"POST /organizationRelationships",
"PUT /organizationRelationships/{id}",
"DELETE /organizationRelationships/{id}",
"POST /organizations/{id}/followers",
"POST /notes",
"PUT /notes/{id}",
"DELETE /notes/{id}",
"POST /files",
"PUT /files/{id}",
"DELETE /files/{id}",
"POST /filters",
"PUT /filters/{id}",
"DELETE /filters",
"DELETE /filters/{id}",
"GET /deals/{id}/persons",
"GET /persons/find",
"GET /persons/search",
"GET /persons/{id}",
"GET /persons/{id}/files",
"GET /persons",
"GET /personFields",
"GET /personFields/{id}",
"GET /persons/{id}/followers",
"GET /organizationFields",
"GET /organizationFields/{id}",
"GET /organizations/{id}/files",
"GET /organizations/{id}/persons",
"GET /organizations/find",
"GET /organizations/search",
"GET /organizations/{id}",
"GET /organizations",
"GET /organizationRelationships",
"GET /organizationRelationships/{id}",
"GET /organizations/{id}/followers",
"GET /notes",
"GET /notes/{id}",
"GET /noteFields",
"GET /files",
"GET /files/{id}",
"GET /files/{id}/download",
"GET /filters",
"GET /filters/{id}"
]
products:read
Products: Read only
Read products, its fields, files, followers and products connected to a deal.
"products:read": [
"GET /deals/{id}/products",
"GET /products",
"GET /products/find",
"GET /products/search",
"GET /products/{id}",
"GET /products/{id}/files",
"GET /productFields",
"GET /productFields/{id}",
"GET /products/{id}/followers"
]
products:full
Products: Full access
Create, read, update and delete products and its fields; add products to deals.
"products:full": [
"POST /products",
"PUT /products/{id}",
"POST /productFields",
"PUT /productFields/{id}",
"POST /products/{id}/followers",
"POST /deals/{id}/products",
"GET /deals/{id}/products",
"GET /products",
"GET /products/find",
"GET /products/search",
"GET /products/{id}",
"GET /products/{id}/files",
"GET /productFields",
"GET /productFields/{id}",
"GET /products/{id}/followers",
"DELETE /products/{id}",
"DELETE /productFields",
"DELETE /productFields/{id}",
"DELETE /deals/{id}/products/{product_attachment_id}",
"DELETE /products/{id}/followers/{id}"
]
users:read
Read users data
Read data about users (people with access to a Pipedrive account), their permissions, roles and followers.
"users:read": [
"GET /users",
"GET /users/{id}",
"GET /users/find",
"GET /users/{id}/followers",
"GET /users/{id}/roleSettings",
"GET /users/{id}/permissions",
"GET /teams",
"GET /teams/{id}",
"GET /teams/{id}/users",
"GET /teams/users/{id}"
]
recents:read
See recent account activity
Read all recent changes occurred in an account. Includes data about activities, activity types, deals, files, filters, notes, persons, organizations, pipelines, stages, products and users.
"recents:read": [
"GET /recents",
"GET /deals/{id}/flow",
"GET /persons/{id}/flow",
"GET /organizations/{id}/flow"
]
search:read
Search for all data
Search across the account for deals, persons, organizations, files and products, and see details about the returned results.
"search:read": [
"GET /searchResults",
"GET /searchResults/field",
"GET /recents",
"GET /deals/find",
"GET /deals/search",
"GET /products/find",
"GET /products/search",
"GET /persons/find",
"GET /persons/search",
"GET /organizations/find",
"GET /organizations/search",
"GET /itemSearch",
"GET /itemSearch/field"
]
admin
Administer account
Allows to do many things that an administrator can do in a Pipedrive company account - create, read, update and delete pipelines and its stages; deal, person and organization fields; activity types; webhooks; users and permissions, etc.
Before requesting this scope, see below how it can effect non-admin users.
"admin": [
"POST /stages",
"PUT /stages/{id}",
"DELETE /stages",
"DELETE /stages/{id}",
"POST /pipelines",
"PUT /pipelines/{id}",
"DELETE /pipelines/{id}",
"GET /webhooks",
"POST /webhooks",
"DELETE /webhooks/{id}",
"GET /users/{id}/blacklistedEmails",
"POST /users",
"POST /users/{id}/blacklistedEmails",
"PUT /users/{id}",
"POST /dealFields",
"PUT /dealFields/{id}",
"DELETE /dealFields",
"DELETE /dealFields/{id}",
"POST /activityTypes",
"PUT /activityTypes/{id}",
"DELETE /activityTypes",
"DELETE /activityTypes/{id}",
"POST /personFields",
"PUT /personFields/{id}",
"DELETE /personFields",
"DELETE /personFields/{id}",
"POST /organizationFields",
"PUT /organizationFields/{id}",
"DELETE /organizationFields",
"DELETE /organizationFields/{id}",
"GET /stages",
"GET /stages/{id}",
"GET /pipelines",
"GET /pipelines/{id}",
"GET /dealFields",
"GET /dealFields/{id}",
"GET /activityTypes",
"GET /personFields",
"GET /personFields/{id}",
"GET /organizationFields",
"GET /organizationFields/{id}",
"POST /teams",
"PUT /teams/{id}",
"POST /teams/{id}/users",
"DELETE /teams/{id}/users"
]
goals:read
Goals: Read only
Read data on all goals.
"goals:read": [
"GET /goals/count/by-{goalAssignee}",
"GET /goals/find",
"GET /goals/find-intervals/custom",
"GET /goals/find-intervals/{period}",
"GET /goals/{id}/results"
]
goals:full
Goals: Full access
Create, read, update and delete goals.
"goals:full": [
"GET /goals/count/by-{goalAssignee}",
"GET /goals/find",
"GET /goals/find-intervals/custom",
"GET /goals/find-intervals/{period}",
"GET /goals/{id}/results",
"POST /goals",
"PUT /goals/{id}",
"DELETE /goals/{id}"
]
leads:full
Leads: Full access
Create, read, update and delete leads and lead labels.
"leads:full": [
"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}"
]
leads:read
Leads: Read only
Read data about leads and lead labels.
"leads:read": [
"GET /leads",
"GET /leads/{id}",
"GET /leadSources",
"GET /leadLabels"
]
phone-integration
Phone calls integration
Enables advanced call integration features like logging call duration and other metadata, and play call recordings inside Pipedrive.
"phone-integration": [
"POST /callLogs",
"DELETE /callLogs/{id}",
"POST /callLogs/{id}/recordings",
"GET /callLogs",
"GET /callLogs/{id}"
]
The admin scope requires the user who is installing an app (from the Pipedrive's Marketplace), to have admin rights within the company. As the Marketplace doesn't restrict non-admin users from installing apps, your app will need to be able to handle users without admin rights installing the app, when the admin scope is required.
When your app requests admin scope access, the app will need to check if it can complete all of the required functionalities/actions through a non-admin user or whether those actions would require the permissions of an Admin. If the request fails, check to see if the user is a non-admin user and/or falls under a certain permission set or a visibility group. You can check that through the GET /users/{id}/permissions
endpoint. For additional information about user restrictions, you can see the list role assignments - GET /users/{id}/roleSettings
and the list user role settings - GET /users/{id}/roleAssignments
.
If an admin has installed the app before any regular user, your app may work correctly for non-admin users. Example use-case:
Your app needs to create activities with a custom activity type. An admin user of a company has installed the app and the custom activity type has been created for their company. Now, when a regular user who's a part of the same company installs the app, your app will be able to create the activities with before created activity type.
Affected use-cases can include your app creating, editing or deleting activity types, stages and pipelines as well as custom fields.
Updated 21 days ago