> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Pipedrive: CRM context in the inbox, activities written back

> Operator walkthrough for the Pipedrive integration: connect via OAuth, the inbound sync of persons, organizations, deals, and activities, AI-agent write-back as Pipedrive activities and notes, and the fixes when a conversation does not match a Pipedrive record.

# Connect Pipedrive end to end

The Pipedrive integration is a junction between Pipedrive records and Orbit conversations:

* **Inbound** — persons, organizations, deals, and activities sync from your Pipedrive account into your Orbit contact book, so agents see open deals and organization context next to each conversation.
* **Outbound** — AI agents working a conversation create activities and log notes on the matched Pipedrive record on behalf of reps, so the Pipedrive timeline shows the channel touch along with its linked deals.

This guide is the numbered checklist operators run when they wire the account up. The endpoint map it links back to is [`/api-reference/integrations`](/api-reference/integrations) — this page is the "do this, then this" walkthrough for the same surface.

## What you'll set up

1. An OAuth connection from Orbit to your Pipedrive account via the generic connect route.
2. The inbound sync — a scheduled pull upserts persons, organizations, deals, and activities into your Orbit contact book.
3. Conversation-to-record matching — inbound messages resolve to a synced Pipedrive person by phone number or email.
4. AI-agent write-back — activities and notes created on Pipedrive records during AI-handled conversations.
5. Pipedrive-side automation — standard Pipedrive Automations that trigger on the created activities.

***

## Step 1 — Connect via OAuth (admin only)

Initiate the connect flow from the Integrations API. **Owner or admin role required**, plus the `integrations:write` scope on the API key — the connect step is the only one that touches provider credentials.

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/integrations/connect \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "integration_id": "pipedrive" }'
```

The response returns an `auth_url`; redirect the browser there and complete the Pipedrive consent screen. A Pipedrive admin typically approves the connection the first time.

<Check>
  After consent, check `GET /api/v1/integrations` — the Pipedrive row should report a connected state.
</Check>

You can also connect from the dashboard: Settings → Integrations → Pipedrive → Connect.

***

## Step 2 — What syncs inbound

Once connected, a scheduled sync pulls Pipedrive changes into your Orbit contact book. The model map for Pipedrive is:

| Pipedrive object | Orbit model |
| ---------------- | ----------- |
| Person           | Contact     |
| Organization     | Company     |
| Deal             | Deal        |
| Activity         | Activity    |

Persons resolve to your existing Orbit contacts by phone number or email, so a Pipedrive person with a filled-in phone or email field links to the conversation contact instead of creating a duplicate.

<Info>
  The sync is poll-based on a schedule of a few minutes. Changes you make in Pipedrive appear in Orbit on the next pass; there is no webhook receiver for Pipedrive today.
</Info>

***

## Step 3 — Match conversations to Pipedrive records

Routing inside Orbit works with or without a Pipedrive match. The match only decides whether write-back lands:

* An inbound message resolves to an Orbit contact as usual.
* If that contact links to a synced Pipedrive person (by phone or email), the person, organization, and open deals appear in the inbox context panel.
* If there is no match yet, the conversation still routes and the write-back is deferred until the person links — usually on the next sync after the phone or email is filled in on the Pipedrive side.

<Check>
  The success marker for linking is the person's organization and open deals rendering in the inbox context panel next to a live conversation.
</Check>

***

## Step 4 — AI-agent write-back

AI agents working a conversation carry Pipedrive tool permissions granted by your role policy. When an agent handles a matched contact it can:

* Create an activity on the linked Pipedrive record (for example, "handled by AI agent — summarized outcome").
* Log a note onto the person or deal timeline.

Because these are ordinary Pipedrive activities and notes, the record timeline, list-view filters, and Automation triggers treat them exactly like entries a rep logged by hand.

<Tip>
  The write-back is fail-open: a revoked token or a Pipedrive outage never blocks the conversation. The activity lands on the next retry once the connection is healthy again.
</Tip>

***

## Step 5 — Build on created activities with Pipedrive Automations

A common pattern: an Automation that fires when an activity is created on a person the AI agent just handled. Your Pipedrive admin decides what it does — typical configurations:

* Move the linked deal to a follow-up stage when the customer replied with order intent.
* Assign the deal owner a due follow-up activity.
* Route the person into a service queue for support-adjacent pipelines.

The integration supplies the trigger object; the Automation is your organization's own configuration, built by your own Pipedrive admin.

***

## Step 6 — Troubleshooting common issues

| Symptom                                                | Cause                                                                   | Fix                                                                                                                                               |
| ------------------------------------------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401` on write-back                                    | Revoked or expired OAuth token                                          | Re-run the connect flow; token refresh is automatic but revocation requires a new consent.                                                        |
| Orbit conversation without a matching Pipedrive person | Phone/email missing on the Pipedrive record, or match pending next sync | Fill the phone or email on the Pipedrive side; the next scheduled sync links the contact.                                                         |
| Pipedrive row shows a stale `last_sync` timestamp      | Scheduled sync falling behind or connection disconnected                | Poll `GET /api/v1/integrations/{id}/status`; reconnect if `connected` is false, and manually catch up with `POST /api/v1/integrations/{id}/sync`. |
| Inbox context panel empty for a matched contact        | Sync ran before linking was established                                 | Refresh the conversation after the next sync pass.                                                                                                |

***

## Related reading

* [Integrations API reference](/api-reference/integrations) — endpoint map for the connect/sync/status surface.
* [HubSpot & Salesforce guide](/guides/hubspot-salesforce-integration) — the same junction pattern for the other CRM providers, including their webhook receivers.
* [Identity resolution](/guides/identity-resolution) — how Orbit decides an inbound event links to an existing contact.