# Pipedrive
> Run your workspace's CRM on Pipedrive: deals, activities and notes written through, outreach logged on the person, and campaigns that stop when Pipedrive says someone has moved on.
Source: https://docs.ayinbox.com/guides/pipedrive/
Pipedrive mode makes Pipedrive your workspace's CRM. The deals, tasks and notes you see in AY Inbox are Pipedrive's records, and your outreach is logged on each person.
Switch to Pipedrive [#switch-to-pipedrive]
Open **Integrations > Pipedrive** and select **Connect**.
Sign in to Pipedrive, pick the company, and approve the permissions.
In the setup wizard, select **Switch to Pipedrive**, then press **Looks good** through the rest.
Finish the wizard. The dashboard fills in as the first pull runs, usually within a minute or two.
Good to know [#good-to-know]
* Every change you make in AY Inbox goes to Pipedrive first. If Pipedrive refuses it, nothing is saved.
* A deal opened in Pipedrive, a label you choose (such as **Customer**) or an unsubscribe holds the person's campaigns.
* Connect as a Pipedrive admin when you can. Without admin rights, the AY Inbox fields are not written and AY Inbox checks for changes every five minutes.
* Opens and clicks are not logged by default.
* Switching back or disconnecting deletes nothing on either side.
How Pipedrive mode works [#how-pipedrive-mode-works]
A workspace can use AY Inbox's own CRM, [HubSpot](/guides/hubspot/) or Pipedrive. In **Pipedrive mode**, Pipedrive is the system of record. The deals, pipelines, tasks and notes you see in AY Inbox are Pipedrive's deals, pipelines, activities and notes, mirrored into AY Inbox so lists, search and the board stay fast, and every change you make in AY Inbox goes to Pipedrive first. Your outreach is logged as activities on each person, and Pipedrive can stop a campaign when a deal opens or a person is labeled a customer.
The basic Pipedrive connection (a person upsert from an [automation](/guides/automations/#actions) or **Push to CRM**) works without Pipedrive mode. This page covers the full mode.
What Pipedrive mode does [#what-pipedrive-mode-does]
* **Deals, pipelines, activities and notes are Pipedrive's.** A deal you create, move or edit in AY Inbox is written to Pipedrive before it is saved here. AY Inbox's tasks are Pipedrive activities. If Pipedrive refuses a change (a missing permission, a deleted record), you see Pipedrive's reason and nothing is saved.
* **Your outreach is logged on the person.** Sends and replies are logged as done **Email** activities with the subject and body, bounces mark the logged email, unsubscribes add a note, and booked meetings become **Meeting** activities.
* **AY Inbox fields** on Pipedrive people carry each person's outreach status, so your team can filter, report and run Pipedrive automations on it.
* **Pipedrive can stop outreach.** A deal opened in Pipedrive, a label you choose (such as **Customer**) or an unsubscribe holds the person's campaigns.
* **The contact panel shows Pipedrive's side.** In the contact drawer and the inbox, a contact shows their Pipedrive owner, label, organization and any fields you choose, and you can change the owner and label in place.
Connect and set up [#connect-and-set-up]
1. Open **Integrations > Pipedrive** and select **Connect**. Sign in to Pipedrive, pick the company, and approve the permissions.
2. The setup wizard opens. Select **Switch to Pipedrive**. AY Inbox reads your labels and fills in the rules from them: an interested reply labels the person **Hot lead**, and people labeled **Customer** are never emailed by a campaign. Every other question also has a working default, so you can press **Looks good** through the rest and adjust later.
3. Finish the wizard. AY Inbox adds its fields to Pipedrive, registers for Pipedrive's change notifications, and starts the first pull: users, pipelines, then deals and recent activities. The dashboard fills in as it runs, usually within a minute or two.
After setup the same page holds the settings and the [sync health](#sync-health-and-fixing-errors) panel. Changing them needs the `manage_settings` permission.
If the workspace runs on HubSpot when you switch, the wizard says so first. Switching makes Pipedrive the CRM instead: HubSpot's mirrored records stay in AY Inbox, nothing is deleted in HubSpot, and HubSpot stays connected for automations.
Connect as a Pipedrive admin when you can. Pipedrive checks every change against the connected user's own permissions, and adding the AY Inbox fields and the change notifications needs an admin (or the contact fields and webhooks permissions). Without them the sync still runs: fields are not written, and AY Inbox checks Pipedrive every five minutes instead of hearing about changes at once.
What syncs [#what-syncs]
| Record | Direction | How |
| --------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Deals | Both ways | AY Inbox writes through to Pipedrive. Changes in Pipedrive arrive within seconds |
| Pipelines and stages | Pipedrive to AY Inbox | Managed in Pipedrive only. Refreshed when they change, and every six hours |
| Activities (AY Inbox tasks) | Both ways | AY Inbox writes through. Activities owned by matched users arrive within seconds |
| Notes | Both ways | AY Inbox writes through. Notes on a linked person arrive within seconds |
| Activity types | Pipedrive to AY Inbox | Your company's own activity types, such as Call, Meeting, Task and Deadline |
| Users | Pipedrive to AY Inbox | Refreshed every six hours and matched to members by email |
| People | Both ways, per field | Owner, labels, organization, unsubscribe status and the fields you map. See [people and field mapping](#people-and-field-mapping) |
| Outreach activity | AY Inbox to Pipedrive | See [activity logged to Pipedrive](#activity-logged-to-pipedrive) |
Changes made in Pipedrive reach AY Inbox through Pipedrive's change notifications, usually within seconds. AY Inbox also checks for changes every fifteen minutes in case a notification was missed, or every five minutes when notifications are not available. Opening a contact in AY Inbox refreshes their Pipedrive record on the spot, and their deals, activities and notes every few hours.
Pipedrive gives each company a daily API budget, shared by every app it uses. AY Inbox reads only what changed and spaces its checks so a normal workspace uses a small part of it.
Deals and pipelines [#deals-and-pipelines]
The Pipelines page lists only your Pipedrive pipelines, and creating, renaming or deleting a pipeline or stage is refused with `crm_managed_externally`: make the change in Pipedrive and it appears in AY Inbox within moments. In the wizard you can limit the mirror to some pipelines; deals in the others are not shown.
In Pipedrive, won and lost are a deal's status, as in AY Inbox: marking a deal won or lost keeps its stage, and moving it between stages does not change its status. Stages carry Pipedrive's deal probability. A deal owned by a Pipedrive user who is not a workspace member shows that user's name.
Deals in a pipeline that only exists in AY Inbox are hidden from the deal table and board while Pipedrive is your CRM. They are not deleted: [copy them into Pipedrive](#copying-your-ay-inbox-crm-into-pipedrive) or [switch back](#switching-back-and-disconnecting) to see them again.
Deals created by an automation's **Create deal** or **Move deal stage** action reach Pipedrive too, through the [sync queue](#sync-health-and-fixing-errors) rather than at once.
Activities [#activities]
The Tasks page shows the Pipedrive activities owned by Pipedrive users who are matched to workspace members. The first pull brings in activities changed in the last 90 days. A person's own activities come in when you open them, whoever owns them. Done email activities are records of an email, not to-dos, so they are not shown as tasks; that includes the ones AY Inbox logs itself.
| AY Inbox | Pipedrive |
| --------------------------------- | ------------------------------------------------------------------------------------------------- |
| Type | The activity type with the same name, else the closest one (Call, Meeting, Email, Deadline, Task) |
| Status `pending` or `in progress` | Not done |
| Status `completed` or `cancelled` | Done |
| Due date and time | Due date and due time |
| Priority | Kept in AY Inbox only |
| Assignee | Activity owner. A member with no matched Pipedrive user cannot be assigned (`crm_owner_unmapped`) |
Creating, editing or deleting a task type is refused with `crm_managed_externally`, because the types are Pipedrive's activity types. Tasks AY Inbox opens by itself, such as [follow-up tasks from replies](/guides/contacts-crm/#follow-up-tasks-from-replies) and an automation's **Create a task**, become Pipedrive activities as well.
People and field mapping [#people-and-field-mapping]
An AY Inbox contact is linked to a Pipedrive person by email address. Linking happens when AY Inbox emails the contact, when you open it, when a person whose address AY Inbox has changes in Pipedrive, and after an [import from a Pipedrive filter](#importing-from-pipedrive-filters).
When AY Inbox emails someone Pipedrive does not have, it creates the person (on by default), owned by the Pipedrive user matched to the member who owns the sending mailbox. With organization creation on (also the default), the new person is linked to the organization named after their company, or their email domain when the company is blank, and the organization is created when Pipedrive has none. Free mail domains such as `gmail.com` never become organizations. With creating people off, someone Pipedrive does not have is simply not logged there.
Each mapped field has a direction:
| Direction | What happens |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| AY Inbox wins | AY Inbox writes the field to Pipedrive when the contact is edited in AY Inbox and each time it emails them |
| Pipedrive wins | A change in Pipedrive is copied onto the AY Inbox contact |
| Most recent | An edit in Pipedrive is copied onto the AY Inbox contact, and an edit in AY Inbox is written to Pipedrive |
The defaults map first name, last name, company and phone to the person's first name, last name, organization and phone, all **Most recent**. Pipedrive keeps a person's name as one field and splits it itself, so first and last name are written together. A custom AY Inbox field maps as `custom:` to any text, number, phone or date field of yours. A blank value in Pipedrive never blanks an AY Inbox field, and the email address is never overwritten from Pipedrive.
You can also pick up to 40 of your Pipedrive fields to show on the contact panel.
Activity logged to Pipedrive [#activity-logged-to-pipedrive]
| In AY Inbox | In Pipedrive | Default |
| ----------------------------------------------- | -------------------------------------------------------------------------------------- | ------- |
| A campaign email is sent | A done Email activity with the subject, the body, the sending mailbox and the campaign | On |
| The person replies | A done Email activity titled `Reply: ` | On |
| An email bounces | The logged email activity is renamed `Bounced: ` | On |
| The person unsubscribes | A note on the person | On |
| A meeting is booked through Calendly or Cal.com | A Meeting activity at the booked time | On |
| An open | The **AY Inbox last opened** field updated, no activity | Off |
| A click | The **AY Inbox last clicked** field updated, no activity | Off |
Each activity is linked to the person, their organization and their open deal. Its owner is the Pipedrive user matched to the member who owns the sending mailbox, otherwise the person's owner. Activity is logged within seconds and never depends on your [webhooks](/guides/webhooks/) or their per-minute limit, so a large send is logged in full.
Opens and clicks are off by default because mail privacy proxies and security scanners open and click on their own. Turned on, they only update the two fields, at most once a day per person, and never create a person in Pipedrive.
AY Inbox fields [#ay-inbox-fields]
AY Inbox adds these custom fields to Pipedrive people when you switch, and keeps them up to date (on by default; turning it off stops every field write, including opens and clicks). A field your team already has with the same name is reused.
| Field | Holds |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AY Inbox status | Contacted, Replied, Interested, Not interested, Meeting booked, Bounced or Unsubscribed. A later send never moves a person back from a reply status to Contacted |
| AY Inbox last campaign | The name of the last campaign that emailed the person |
| AY Inbox last contacted | When AY Inbox last emailed the person |
| AY Inbox last replied | When the person last replied |
| AY Inbox reply intent | How AY Inbox classified the latest reply |
| AY Inbox last opened | Last open, when open logging is on |
| AY Inbox last clicked | Last click, when click logging is on |
| Open in AY Inbox | A link that opens the contact in AY Inbox |
Users [#users]
Pipedrive's users are matched to workspace members by email address. Where the addresses differ, pick the member by hand on the Pipedrive page; a match you choose is kept and never replaced by the email match. Matching decides:
* whose activities appear on the Tasks page
* who owns the email activities a mailbox logs, and the people it creates
* which Pipedrive user a deal or activity gets when you assign it to a member in AY Inbox
Positive replies [#positive-replies]
When a reply is classified as interested, AY Inbox can:
* **label the person** (by default **Hot lead**, when your company has that label). The label replaces the person's current one
* **add them to the Leads Inbox** as a lead for the person and their organization, owned by whoever owns the mailbox that got the reply (off by default)
* **create a deal** in a pipeline and stage you choose (off by default)
The lead and the deal are both skipped when the person already has an open deal. The follow-up task comes from your existing [reply follow-up setting](/guides/contacts-crm/#follow-up-tasks-from-replies) and becomes a Pipedrive activity like any other task.
Exit rules [#exit-rules]
Exit rules hold a person in every campaign they are in when Pipedrive says they have moved on, so nobody gets a follow-up after becoming a deal or a customer. A held lead stays held until someone resumes it; the hold shows the reason, such as "A deal was opened in Pipedrive".
| Rule | Default |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| A deal is opened for the person in Pipedrive | On. Only deals created in the last 48 hours count, so the first pull's existing deals stop nobody |
| The person gets a label you choose | On, for **Customer** when your company has that label |
| The person unsubscribes in Pipedrive | On. Needs Pipedrive Campaigns, which records email marketing status. The address is added to the [suppression list](/guides/unsubscribe/) |
Import guards [#import-guards]
Guards decide who an [import from a Pipedrive filter](#importing-from-pipedrive-filters) leaves out:
| Guard | Default |
| -------------------------------------------------- | ----------------------------------------------------- |
| Skip people who unsubscribed in Pipedrive | On |
| Skip people with these labels | On, for **Customer** when your company has that label |
| Skip people with an open deal | On |
| Skip people owned by someone outside the workspace | Off |
Working from inside Pipedrive [#working-from-inside-pipedrive]
The **AY Inbox panel** on person and deal pages shows the person's AY Inbox status, each campaign they are in with its step, status and last activity, and why a lead is paused, with a link that opens them in AY Inbox. Its two actions work from Pipedrive itself:
* **Add to AY Inbox campaign** opens a picker of your campaigns and adds the person. Someone new to AY Inbox is created from the Pipedrive person, unless they unsubscribed in Pipedrive
* **Pause in AY Inbox** pauses or resumes every campaign the person is in
On a deal page the panel shows the deal's person. The panel acts as the AY Inbox member matched to the Pipedrive user viewing it (see [users](#users)), with that member's role:
| In the panel | The member needs |
| ---------------------------------------------- | ------------------------------------ |
| See the person's AY Inbox status and campaigns | View campaigns and view contacts |
| Add to campaign | Manage campaigns and manage contacts |
| Pause or resume | Manage campaigns |
A Pipedrive user with no matched member, or whose member is still invited, is banned from signing in, or lacks the permission, sees why in the panel and changes nothing. Every panel and modal request must carry the token Pipedrive signs for it with your app's client secret, issued within the last 15 minutes or expiring within a day; a token without either is refused. The panel needs the Pipedrive company to be in Pipedrive mode in exactly one AY Inbox workspace. On a self-hosted instance the panel is part of your own Pipedrive app; see [self-hosting](#self-hosting).
Importing from Pipedrive filters [#importing-from-pipedrive-filters]
From **Contacts**, choose **Import from Pipedrive** and pick one of your saved people filters. The preview counts who would come in and who is skipped, by reason: unsubscribed, label, open deal, owned by someone outside the workspace, no email address, and duplicate address. Continue, and the filter becomes an ordinary contact import, finished in the usual [import review](/guides/contacts-crm/#importing) where you pick the campaign, labels and duplicate handling.
One import takes up to 25,000 people; a larger filter is cut off at that number and the preview says so. The imported contacts are linked to their Pipedrive persons a couple of minutes later, so their first sends log against the right person.
Copying your AY Inbox CRM into Pipedrive [#copying-your-ay-inbox-crm-into-pipedrive]
When a workspace that used AY Inbox's CRM switches, its own deals, tasks and notes are not in Pipedrive yet. Records mirrored from a CRM the workspace used before (such as HubSpot) are not counted. The Pipedrive page counts them and copies the kinds you pick, once:
* **Deals** move onto your first Pipedrive pipeline. Each keeps its stage when Pipedrive has a stage with the same name, and otherwise goes to the first stage. Won and lost deals stay won and lost
* **Tasks** become activities and **notes** become notes, with their person and deal
A record already in Pipedrive is never copied twice, so running it again only picks up what was missed. An AY Inbox deal, task or note you edit after switching is also created in Pipedrive at that moment.
Sync health and fixing errors [#sync-health-and-fixing-errors]
The Pipedrive page shows what is waiting, what failed in the last runs, how many records are mirrored, and when each pull (users, pipelines, deals, activities, people), the change notifications and the AY Inbox fields last ran with any error they hit. **Sync now** starts a full pull; a second one within a minute is refused with `crm_sync_running`.
Changes you make in the dashboard go to Pipedrive while you wait. Activity logging, automation-written records, large bulk changes and copies go through a queue that retries a failure with growing gaps (a minute, five minutes, half an hour, up to several hours) before marking it failed. Failed items stay listed for 30 days with a plain-language reason. **Retry** sends them again and **Discard** drops them.
| You see | What to do |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Reconnect Pipedrive | Pipedrive revoked AY Inbox's access, or the connected user may not make that change. Reconnect from **Integrations**, as an admin when you can |
| Pipedrive refused the change | Pipedrive's own rule, shown in its words. Fix it in Pipedrive or on the record, then retry |
| This record no longer exists in Pipedrive | It was deleted in Pipedrive. Discard the item |
| That member is not a Pipedrive user yet | Match the member to a Pipedrive user in [users](#users) |
| Pipedrive did not answer | Pipedrive was slow, down, or the company used up its daily API budget. It retries by itself |
| Instant updates need this instance reachable over HTTPS | Pipedrive cannot reach the instance. AY Inbox checks every five minutes instead |
AY Inbox keeps its calls well under Pipedrive's burst limit for each company (30 requests every two seconds and 4 searches, shared across every AY Inbox process), and waits and retries when Pipedrive asks it to slow down.
Switching back and disconnecting [#switching-back-and-disconnecting]
Choosing **AY Inbox** as the CRM again, switching to HubSpot, or disconnecting Pipedrive stops the sync and the activity logging. Switching removes AY Inbox's change notifications from Pipedrive; after a disconnect, AY Inbox answers their deliveries as gone and Pipedrive retires them. Nothing is deleted on either side: the deals, pipelines, tasks and notes that were mirrored stay in AY Inbox as ordinary records you can edit, the hidden AY Inbox-only pipelines come back, and Pipedrive keeps everything that was written there, including the AY Inbox fields. Switching back to the same Pipedrive company later picks up the same records rather than duplicating them.
Self-hosting [#self-hosting]
A self-hosted instance uses its own Pipedrive app. Create one in the Pipedrive Developer Hub, then:
1. Set the callback URL to `BACKEND_PUBLIC_URL` plus `/integrations/oauth/callback`, or to the value of `INTEGRATIONS_OAUTH_REDIRECT_URL` when you set one.
2. Give the app these scopes: deals (full access), contacts (full access), activities (full access), users (read), search (read), leads (full access), contact fields (full access) and webhooks (full access). Pipedrive mode needs the first four; without the others, lead creation, the AY Inbox fields or instant updates are skipped.
3. Set `PIPEDRIVE_OAUTH_CLIENT_ID` and `PIPEDRIVE_OAUTH_CLIENT_SECRET` on the backend and the consumer, and set `APP_URL` so the **Open in AY Inbox** field points at your dashboard. See [configuration](/development/configuration/#integrations).
4. Optionally add the [AY Inbox panel](#working-from-inside-pipedrive) under **App extensions**: a JSON panel and two JSON modals, whose schemas are in the repository's `pipedrive-app/` directory. The steps are in [configuration](/development/configuration/#pipedrive-app).
The consumer runs the pull and the sync queue. Change notifications are registered by AY Inbox itself when a workspace switches, one set per connection, delivered to `/api/v1/integrations/pipedrive/webhooks/`. They need `BACKEND_PUBLIC_URL` to be an `https` address Pipedrive can reach; without one, AY Inbox checks Pipedrive every five minutes instead. Pipedrive authenticates each delivery with a password AY Inbox derives for that connection from the client secret, and a delivery only makes AY Inbox read the named record sooner: it always reads the record from Pipedrive itself, and removes a mirrored record only when Pipedrive answers that it is gone.
Moving a workspace [#moving-a-workspace]
A [workspace export](/guides/workspace-export-import/) carries the CRM mode, its setup choices, the user matches, which AY Inbox record is which Pipedrive record, and each contact's Pipedrive details, so the destination keeps updating the same Pipedrive records instead of creating duplicates. The sync queue and the pull checkpoints stay behind; the destination starts its own pull and registers its own change notifications. Reconnect Pipedrive on the destination unless it uses the same Pipedrive app and the archive carried credentials.
FAQ [#faq]
**Which Pipedrive plans work?** Every plan has the deals, people, activities, notes and filters Pipedrive mode uses. Unsubscribe status is only recorded on companies with Pipedrive Campaigns, so the unsubscribe exit rule and guard do nothing without it.
**Why are emails logged as activities?** Pipedrive only lets an app add email through its own mailbox sync. A done Email activity is the closest Pipedrive record: it sits on the person's timeline with the subject and body, and counts in Pipedrive's activity reports.
**Why are opens off?** Mail privacy proxies and security scanners open and click automatically, so opens are a weak signal. Turned on, they only update the **AY Inbox last opened** and **AY Inbox last clicked** fields.
**What happens to my data when I disconnect?** Everything that was mirrored stays in AY Inbox as ordinary records, and nothing is removed from Pipedrive. See [switching back and disconnecting](#switching-back-and-disconnecting).
**Can I edit pipelines in AY Inbox?** No, while Pipedrive is your CRM. Edit them in Pipedrive and they update in AY Inbox within moments.
**Does every member need a Pipedrive seat?** No. Members without a matched user still see deals, activities and notes; they cannot be assigned Pipedrive deals or activities, and their mailboxes log email under the person's owner.
Next steps [#next-steps]