Skip to main content

Pipedrive — Application Overview

Pipedrive is a CRM platform used by sales, customer success, and revenue operations teams to manage leads, deals, contacts, and sales activities.

The Pipedrive integration within the Wrk platform allows you to automate CRM Wrkflows by calling the Pipedrive API through Wrk Actions.

This document provides an overview of how Pipedrive integrates into Wrk, how authentication works, general API behaviour, and a list of available Wrk Actions.

eneral API behaviour, and a list of available Wrk Actions.

Authentication​

Pipedrive supports multiple authentication methods within Wrk, allowing flexibility depending on workspace policies and use cases.

Supported Authentication Methods​

MethodDescription
OAuth 2.0Recommended method using Pipedrive’s OAuth flow
API TokenStatic token provided by Pipedrive

OAuth 2.0​

When connecting Pipedrive via OAuth:

  • Authentication is initiated directly inside Wrk.
  • Users are redirected to Pipedrive to authorize access.
  • Wrk receives an access token that is used for all subsequent API calls.
  • Tokens are scoped based on the permissions granted during authorization

API token​

For API token authentication, Pipedrive requires the token to be sent on every request using the x-api-token header.

Important Notes

  • The API token is tied to a specific user and company and provides access to that user’s data.
  • Only one active API token can exist at a time; regenerating it will break existing integrations using the old token.

General API Behaviour​

Base URL and response structure​

Most Pipedrive API calls return JSON responses that commonly include:

  • success
  • data
  • additional_data (often used for pagination metadata)

Pagination​

Most list-style endpoints use offset-based pagination with:

  • start (offset, default 0)
  • limit (page size, default 100)

Pagination details are returned in additional_data.pagination, including:

  • more_items_in_collection (whether more results exist)
  • next_start (the next offset to request)

Limit maximums

  • The documented maximum limit value is 500 for offset pagination.
  • Some endpoints may enforce lower maximums (for example, certain file-list endpoints cap limit at 100 even if a higher value is supplied).

Why this matters

  • Wrkflows that need “all deals” (or similar) should always loop through pages using next_start until more_items_in_collection is false.

Rate limiting​

Pipedrive enforces burst limits using a rolling 2-second window, and limits are considered per token (not per company).

Burst limits vary by plan and auth type (API token vs OAuth). Pipedrive also notes that the Search API has its own burst limits.

Rate limit headers

Responses include headers such as:

  • x-ratelimit-limit
  • x-ratelimit-remaining
  • x-ratelimit-reset
  • x-daily-requests-left (noted as applicable to certain request types/auth scenarios)

Throttling and blocking

  • When burst limits are exceeded, requests can return HTTP 429.
  • Continued high-volume traffic that ignores limiting responses (especially for API token integrations) can lead to HTTP 403 blocking behavior.

Custom fields​

Pipedrive custom fields appear in API payloads using an account-specific field API key (often a long identifier). These keys are not universal and differ per Pipedrive account.

How to find a custom field’s API key

  • In Pipedrive: Settings → Data fields → (choose entity type), then use the field’s menu to Copy API key.

Referencing custom fields

  • When creating or updating an entity (for example, a deal), include the custom field API key as a property in the request payload.

Important Notes

  • The field API key cannot be renamed (the display name can).

Available Wrk Actions​

  • Add a discount to a deal
  • Add a follower to a deal
  • Add a lead
  • Add a new activity
  • Add a new deal
  • Add a new person
  • Add a new user
  • Add a participant to a deal
  • Add a product to a deal
  • Add a task
  • Add an installment to a deal
  • Create deal
  • Delete a deal
  • Delete a lead
  • Delete a person
  • Delete a task
  • Delete an activity
  • Merge two deals
  • Retrieve all activities
  • Retrieve all activity fields
  • Retrieve all activity types
  • Retrieve all deals
  • Retrieve all lead fields
  • Retrieve all leads
  • Retrieve all person fields
  • Retrieve all persons
  • Retrieve all pipelines
  • Retrieve all products
  • Retrieve all projects
  • Retrieve all tasks
  • Retrieve all users
  • Retrieve deals
  • Retrieve details of a deal
  • Retrieve details of a person
  • Retrieve details of a project
  • Retrieve details of a task
  • Retrieve details of an activity
  • Retrieve files attached to a deal
  • Retrieve leads
  • Retrieve one lead
  • Retrieve one user
  • Retrieve persons
  • Retrieve products
  • Retrieve users by name
  • Update a deal
  • Update a lead
  • Update a person
  • Update a task
  • Update an activity
  • Update user details

Additional Resources​