openapi: 3.0.1
info:
title: Pipedrive API v1 Activities Oauth API
version: 1.0.0
description: 'Activities are appointments/tasks/events on a calendar that can be associated with a deal, a lead, a person and an organization. Activities can be of different type (such as call, meeting, lunch or a custom type - see ActivityTypes object) and can be assigned to a particular user. Note that activities can also be created without a specific date/time.
'
servers:
- url: https://api.pipedrive.com/v1
tags:
- name: Oauth
description: 'Using OAuth 2.0 is necessary for developing apps that are available in the Pipedrive Marketplace. Authorization via OAuth 2.0 is a well-known and stable way to get fine-grained access to an API. To retrieve OAuth2 tokens you should send requests to the `https://oauth.pipedrive.com` domain. After registering the app, you must add the necessary server-side logic to your app to establish the OAuth flow. Please read more about authorization step on the [Pipedrive Developers page](https://pipedrive.readme.io/docs/marketplace-oauth-authorization).
'
paths:
/oauth/authorize:
get:
summary: Requesting authorization
description: Authorize a user by redirecting them to the Pipedrive OAuth authorization page and request their permissions to act on their behalf. This step is necessary to implement only when you allow app installation outside of the Marketplace.
operationId: authorize
x-token-cost: 0
servers:
- url: https://oauth.pipedrive.com
tags:
- Oauth
parameters:
- in: query
name: client_id
required: true
schema:
type: string
description: The client ID provided to you by the Pipedrive Marketplace when you register your app
- in: query
name: redirect_uri
required: true
schema:
type: string
description: The callback URL you provided when you registered your app. Authorization code will be sent to that URL (if it matches with the value you entered in the registration form) if a user approves the app install. Or, if a customer declines, the corresponding error will also be sent to this URL.
- in: query
name: state
schema:
type: string
description: 'You may pass any random string as the state parameter and the same string will be returned to your app after a user authorizes access. It may be used to store the user''s session ID from your app or distinguish different responses. Using state may increase security; see RFC-6749.
'
responses:
'200':
description: Authorize user in the app.
content:
text/html:
example: 'As a result of the request, the customer will see a page with the confirmation dialog, which will present the details of your app (title, company name, icon) and explain the permission scopes that you have set for the app. Customers should confirm their wish to install the app by clicking "Allow and install" or deny authorization by clicking "Cancel".
'
/oauth/token:
post:
summary: Getting the tokens
description: After the customer has confirmed the app installation, you will need to exchange the `authorization_code` to a pair of access and refresh tokens. Using an access token, you can access the user's data through the API.
operationId: get-tokens
x-token-cost: 0
servers:
- url: https://oauth.pipedrive.com
tags:
- Oauth
security:
- basic_authentication: []
parameters:
- in: header
name: Authorization
required: true
schema:
type: string
description: Base 64 encoded string containing the `client_id` and `client_secret` values. The header value should be `Basic <base64(client_id:client_secret)>`.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
title: getTokensRequest
type: object
properties:
grant_type:
type: string
enum:
- authorization_code
- refresh_token
default: authorization_code
description: Since you are trying to exchange an authorization code for a pair of tokens, you must use the value "authorization_code"
code:
type: string
description: The authorization code that you received after the user confirmed app installation
redirect_uri:
type: string
description: The callback URL you provided when you registered your app
responses:
'200':
description: Returns user Oauth2 tokens.
content:
application/json:
schema:
title: GetTokensResponse
type: object
properties:
access_token:
type: string
description: You need to use an `access_token` for accessing the user's data via API. You will need to [refresh the access token](https://pipedrive.readme.io/docs/marketplace-oauth-authorization#step-7-refreshing-the-tokens) if the `access_token` becomes invalid.
token_type:
type: string
description: The format of the token. Always "Bearer".
refresh_token:
type: string
description: A refresh token is needed when you refresh the access token. refresh_token will expire if it isn't used in 60 days. Each time refresh_token is used, its expiry date is reset back to 60 days.
scope:
type: string
description: List of scopes to which users have agreed to grant access within this `access_token`
expires_in:
type: integer
description: The maximum time in seconds until the `access_token` expires
api_domain:
type: string
description: The base URL path, including the company_domain, where the requests can be sent to
example:
access_token: v1u:AQIBAHj+LzTNK1yuuuaLqifzhWb9crUNKTpk4FlQ9rjnXqp/6AErhI98syaV25RmpLJLIgOkAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMbGNxa4UccVoXAmLNAgEQgDsiQ7cNdoRBJeFr1i3KW84RYyM1Qtwq1oSBJOl/NFQdVjDI2iQH0LBhS28DbL2KDvoVIihea9Ryt/9rIQ==:RIDnTOIXo8QirT3DMYw0Y0s8xBbxz59f5IMq7T7WhSz313e2MXRHB6g+8OTNCSqVO7QsUhluoAmOfBP1FNkPycy9txn7t2Uoz9y/JDVf4Givv4MMiK/Xq3I7hO4N6FeD+2GqDJDBn24OW6b0SRIr4FEROhGo3BpcPRGehv46NLn1n5LrqXrQwO9qrGD4gIZe40oO2IQgGL9QAPDfqvZ+JhUtcpAipRLp7cCDRfYU8+sdOFJ+hLffqC8isFcV6iPsNrmj
token_type: Bearer
expires_in: 3599
refresh_token: 1:1:2a5496a8bdd0f829dcb09dc8ba82b188f0ea4481
scope: base
api_domain: https://user-company.pipedrive.com
/oauth/token/:
post:
summary: Refreshing the tokens
description: The `access_token` has a lifetime. After a period of time, which was returned to you in `expires_in` JSON property, the `access_token` will be invalid, and you can no longer use it to get data from our API. To refresh the `access_token`, you must use the `refresh_token`.
operationId: refresh-tokens
x-token-cost: 0
servers:
- url: https://oauth.pipedrive.com
tags:
- Oauth
security:
- basic_authentication: []
parameters:
- in: header
name: Authorization
required: true
schema:
type: string
description: Base 64 encoded string containing the `client_id` and `client_secret` values. The header value should be `Basic <base64(client_id:client_secret)>`.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
title: getTokensRequest
type: object
properties:
grant_type:
type: string
enum:
- authorization_code
- refresh_token
default: refresh_token
description: Since you are to refresh your access_token, you must use the value "refresh_token"
refresh_token:
type: string
description: The refresh token that you received after you exchanged the authorization code
responses:
'200':
description: Returns user Oauth2 tokens.
content:
application/json:
schema:
title: GetTokensResponse
type: object
properties:
access_token:
type: string
description: You need to use an `access_token` for accessing the user's data via API. You will need to [refresh the access token](https://pipedrive.readme.io/docs/marketplace-oauth-authorization#step-7-refreshing-the-tokens) if the `access_token` becomes invalid.
token_type:
type: string
description: The format of the token. Always "Bearer".
refresh_token:
type: string
description: A refresh token is needed when you refresh the access token. refresh_token will expire if it isn't used in 60 days. Each time refresh_token is used, its expiry date is reset back to 60 days.
scope:
type: string
description: List of scopes to which users have agreed to grant access within this `access_token`
expires_in:
type: integer
description: The maximum time in seconds until the `access_token` expires
api_domain:
type: string
description: The base URL path, including the company_domain, where the requests can be sent to
example:
access_token: v1u:AQIBAHj+LzTNK1yuuuaLqifzhWb9crUNKTpk4FlQ9rjnXqp/6AErhI98syaV25RmpLJLIgOkAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMbGNxa4UccVoXAmLNAgEQgDsiQ7cNdoRBJeFr1i3KW84RYyM1Qtwq1oSBJOl/NFQdVjDI2iQH0LBhS28DbL2KDvoVIihea9Ryt/9rIQ==:RIDnTOIXo8QirT3DMYw0Y0s8xBbxz59f5IMq7T7WhSz313e2MXRHB6g+8OTNCSqVO7QsUhluoAmOfBP1FNkPycy9txn7t2Uoz9y/JDVf4Givv4MMiK/Xq3I7hO4N6FeD+2GqDJDBn24OW6b0SRIr4FEROhGo3BpcPRGehv46NLn1n5LrqXrQwO9qrGD4gIZe40oO2IQgGL9QAPDfqvZ+JhUtcpAipRLp7cCDRfYU8+sdOFJ+hLffqC8isFcV6iPsNrmj
token_type: Bearer
expires_in: 3599
refresh_token: 1:1:2a5496a8bdd0f829dcb09dc8ba82b188f0ea4481
scope: base
api_domain: https://user-company.pipedrive.com
components:
securitySchemes:
basic_authentication:
type: http
scheme: basic
description: Base 64 encoded string containing the `client_id` and `client_secret` values. The header value should be `Basic <base64(client_id:client_secret)>`.
api_key:
type: apiKey
name: x-api-token
in: header
oauth2:
type: oauth2
description: For more information, see https://pipedrive.readme.io/docs/marketplace-oauth-authorization
flows:
authorizationCode:
authorizationUrl: https://oauth.pipedrive.com/oauth/authorize
tokenUrl: https://oauth.pipedrive.com/oauth/token
refreshUrl: https://oauth.pipedrive.com/oauth/token
scopes:
base: Read settings of the authorized user and currencies in an account
deals:read: 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:full: 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)
mail:read: Read mail threads and messages
mail:full: Read, update and delete mail threads. Also grants read access to mail messages
activities:read: Read activities, its fields and types; all files and filters
activities:full: Create, read, update and delete activities and all files and filters. Also includes read access to activity fields and types
contacts:read: Read the data about persons and organizations, their related fields and followers; also all notes, files, filters
contacts:full: Create, read, update and delete persons and organizations and their followers; all notes, files, filters. Also grants read access to contacts-related fields
products:read: Read products, its fields, files, followers and products connected to a deal
products:full: Create, read, update and delete products and its fields; add products to deals
deal-fields:full: Create, read, update and delete deal fields
product-fields:full: Create, read, update and delete product fields
contact-fields:full: Create, read, update and delete person and organization fields
projects:read: Read projects and its fields, tasks and project templates
projects:full: Create, read, update and delete projects and its fields; add projects templates and project related tasks
users:read: Read data about users (people with access to a Pipedrive account), their permissions, roles and followers
recents:read: 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
search:read: Search across the account for deals, persons, organizations, files and products, and see details about the returned results
admin: 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; users and permissions, etc. It also allows the app to create webhooks and fetch and delete webhooks that are created by the app
leads:read: Read data about leads and lead labels
leads:full: Create, read, update and delete leads and lead labels
phone-integration: Enables advanced call integration features like logging call duration and other metadata, and play call recordings inside Pipedrive
goals:read: Read data on all goals
goals:full: Create, read, update and delete goals
video-calls: Allows application to register as a video call integration provider and create conference links
messengers-integration: Allows application to register as a messengers integration provider and allows them to deliver incoming messages and their statuses