Pipedrive API Documentation

The testing-readme Developer Hub

Welcome to the testing-readme developer hub. You'll find comprehensive guides and documentation to help you start working with testing-readme as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Scopes and permission explanations

Last updated October 15, 2018

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.

List of scopes

Here's our mapping of API endpoints to access scopes:

Scope
Name in the Marketplace Manager with description
Endpoints grouped under this scope

base

Access to basic information
Read the settings of the authorized user and currencies in an account.
:warning+: 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/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"
]

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/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"
"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/{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/{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",
"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/{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/{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/{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 /deals/{id}/products",
"GET /deals/{id}/products",
"GET /products",
"GET /products/find",
"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}"
]

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

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 /products/find",
"GET /persons/find",
"GET /organizations/find"
]

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.

"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}"
]

Scopes and permission explanations


Last updated October 15, 2018

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.