Pipedrive

What your agents can doCopy Anchor Link

Agents can call Pipedrive's v1 and v2 REST APIs. Helios authenticates requests with your API token or OAuth connection.

• Look up a deal, person, or organization before a call, with its notes and activities
• Create and update deals, leads, people, and organizations from a request
• Move deals between stages and mark them won or lost
• Add notes and schedule calls, meetings, and other activities
• Report on a pipeline by stage, owner, or value

What an agent can reach depends on how you connect:

• Pipedrive API Token: an agent can do what the token's user can do in Pipedrive.
• Your own Pipedrive OAuth app: an agent can only call the endpoints that the app's scopes allow, within what the connected user can do. Turn on every scope in the list below for the endpoints you need. The endpoints under the admin scope only work when a Pipedrive admin connects.

Agents can only reach your company domain, such as https://acme.pipedrive.com. Every call uses your company's daily API token budget. See Limits.

AuthenticationCopy Anchor Link

See Integration authentication for how credentials are stored and injected.

Pipedrive API TokenCopy Anchor Link

You need a Pipedrive user whose permission set has use API turned on. The token has that user's rights, so an admin covers the whole company.

1. In Pipedrive, open Settings → Personal preferences → API, and copy your personal API token. If API isn't there, ask an admin to open Manage users → Permission sets, choose your set, and turn on use API.
2. In Helios, choose Pipedrive API Token and paste the token into API Token.
3. Enter your Company Domain, the subdomain in your Pipedrive URL, such as acme in acme.pipedrive.com. The full URL, such as https://acme.pipedrive.com, also works.
4. Save.

Pipedrive records every change made with the token as the user who owns it. A user has a different token for each company they belong to, and only one active token at a time. If you change the token in Pipedrive, the old one stops working. Enter the new one in API Token through Manage and save.

Your own Pipedrive OAuth appCopy Anchor Link

Pipedrive apps are created in Developer Hub, which is only available on a developer sandbox account.

1. Sign up for a developer sandbox account. In Pipedrive, click your profile name, find the sandbox company, and choose Developer Hub.

2. Click Create an app, then Create private app.

3. On the Basic info tab, enter an app name and this Callback URL, then click Save:

   Copy Text

   https://api.heliosapp.com/integrations/pipedrive/oauth_callback

4. On the OAuth & access scopes tab, turn on every scope below, choosing full access where Pipedrive offers read only or full access, and save:

   Scope	Label in Developer Hub	What it's for
   base	Access to basic information	The connected user's settings and currencies. Always on
   deals:full	Deals: Full access	Deals, their products, installments, participants, followers, files, notes, and filters
   activities:full	Activities: Full access	Calls, meetings, and other activities
   contacts:full	Contacts: Full access	People and organizations
   leads:full	Leads: Full access	Leads and lead labels
   products:full	Products: Full access	Products
   projects:full	Projects: Full access	Projects, boards, phases, and tasks
   goals:full	Goals: Full access	Goals
   mail:full	Mail: Full access	Mail threads and messages
   deal-fields:full	Deal fields: Full access	Custom deal fields
   contact-fields:full	Contact fields: Full access	Custom person and organization fields
   product-fields:full	Product fields: Full access	Custom product fields
   project-fields:full	Project fields: Full access	Custom project fields
   users:read	Read users data	Users, their permissions and roles, and the Owner filter
   recents:read	See recent account activity	Recent changes and changelogs
   search:read	Search for all data	Search
   phone-integration	Call logs	Call logs and their recordings
   video-calls	Video calls integration	Registering as a video call provider. Skip it if Developer Hub doesn't list it
   messengers-integration	Messaging integration	Registering as a messaging provider
   webhooks:full	Webhooks: Full access	Registering the webhook for triggers
   admin	Administer account	Pipelines, stages, custom fields, activity types, users, roles, and permission sets

5. Copy the Client ID and Client Secret from the same tab.

6. Click Change to live. A draft app can only be installed by users of the sandbox company.

7. In Helios, choose Your own Pipedrive OAuth app and enter Client ID and Client Secret.

8. Save, then click Allow and install in Pipedrive.

Pipedrive sets scopes on the app, not on each request, so Helios asks for no scopes of its own and has no Admin access option for Pipedrive. A user who isn't a Pipedrive admin can still install an app with admin. The endpoints under it then fail for that user. Helios uses the company domain that Pipedrive returns when you connect.

If you add scopes to the app later, connect again so the token gets them. Access tokens last 60 minutes, and Helios renews them with the refresh token. A refresh token expires after 60 days without use, so Helios also renews the token once a week. If you change the client secret, enter the new one in Client Secret through Manage and connect again. If the app is uninstalled, connect again.

TriggersCopy Anchor Link

Pipedrive can start a Workflow when something happens in your company account. Helios registers one webhook named Helios in Pipedrive when you save the connection. It covers every object and action in the table below, so there is nothing to set up in Pipedrive. With an API token, the user registers it under their own permission level. With an OAuth app, the app needs webhooks:full. Deleting the connection removes the webhook.

• Pipeline matches deals and stages in the pipelines you pick from a list.
• Owner matches records owned by the users you pick from a list.
• Activity type matches activities of the types you pick from a list, such as Call or Meeting.
• Moved to stage matches only updates that changed the deal's stage, when the new stage is one you pick from a list.
• Status changed to matches only updates that changed the deal's status to one you pick: Open, Won, or Lost.
• Done changed to matches only updates that marked an activity or task as Done or Not done.
• Every filter is optional. Without filters, every event matches. A deleted event matches Pipeline, Owner, and Activity type against the record as it was before it was deleted.

The field definition events, such as deal_field.updated, report a custom field being added, renamed, or removed, or its options changing. To start a run when a field's value changes on a record, use that record's updated event, such as deal.updated.

Some events need a Pipedrive feature:

• Project events (board, phase, project, project_field, and task) need Projects. It's included in Premium and Ultimate, and a paid add-on on Lite and Growth. See Projects: billing and subscription.
• deal_installment events need Growth or a higher plan. See Recurring products and installments.

When you save the connection, Helios checks whether your company has these features. The trigger picker shows the events of a missing feature as unavailable, with the reason. If you change your Pipedrive plan, save the connection again to check again.

Pipedrive only sends an event when the connected user can see the record. When a record is merged into another, Pipedrive sends a deleted event for the merged record and an updated event for the record it was merged into.

Pipedrive doesn't sign webhook deliveries. The webhook carries HTTP Basic credentials that Helios generates, and Helios rejects deliveries without them.

Pipedrive waits 10 seconds for each delivery, and retries a failed one 3 times, after 3, 30, and 150 seconds. After 10 failed first attempts, Pipedrive pauses the webhook for 30 minutes, and events in that time are lost. If the webhook has no successful delivery for 3 days in a row, Pipedrive deletes it. Save the connection again to register it again. See Pipedrive's webhooks guide.

Check that it worksCopy Anchor Link

• The connection: after you save, the connection's status shows Connected. Error means Pipedrive rejected the token. See Common errors.
• A trigger:
  1. Add deal.created to a workflow with no filters.
  2. Create a test deal in Pipedrive.
  3. Check that a run starts. Then open the connection in Helios and click Webhook events to see the event.
• Pipedrive's side: with an API token, open Settings → Tools and apps → Webhooks. The Helios webhook is listed with the status of its last delivery. Webhooks that an OAuth app creates don't show in Pipedrive's web app.

Common errorsCopy Anchor Link

LimitsCopy Anchor Link

• Daily API token budget: each company gets 30,000 tokens × the plan multiplier × the number of seats, shared by every API token and OAuth app. The multiplier is 1 on Lite, 2 on Growth, 5 on Premium, and 7 on Ultimate. Token costs vary by endpoint and API version. Check the endpoint's Cost in Pipedrive's API reference. Over the budget, Pipedrive answers 429 until the next day. See Pipedrive's rate limiting.
• Burst limits: an API token can make 20 to 120 requests per 2 seconds, and an OAuth app 80 to 480, depending on the plan. Search is limited to 10 requests per 2 seconds.
• Webhooks: Pipedrive allows 40 webhooks per user, and each Helios connection uses one.