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 — this page is the “do this, then this” walkthrough for the same surface.

What you’ll set up

An OAuth connection from Orbit to your Pipedrive account via the generic connect route.
The inbound sync — a scheduled pull upserts persons, organizations, deals, and activities into your Orbit contact book.
Conversation-to-record matching — inbound messages resolve to a synced Pipedrive person by phone number or email.
AI-agent write-back — activities and notes created on Pipedrive records during AI-handled conversations.
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.

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.

Connect response

{
  "data": {
    "auth_url": "https://app.pipedrive.com/oauth/authorize?client_id=...&redirect_uri=...&state=..."
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-10-04T10:30:00.000Z"
  }
}

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

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

Step 2 — Confirm the connection worked

Once the OAuth consent completes, verify the integration shows as connected and the sync models are active:

curl -X GET https://api.orbit.devotel.io/api/v1/integrations/pipedrive/status \
  -H "X-API-Key: dv_live_sk_your_key_here"

Status response (connected)

{
  "data": {
    "connected": true,
    "connection_id": "conn_7f3a2b1c",
    "provider": "pipedrive",
    "created_at": "2026-10-04T10:30:05.000Z",
    "updated_at": "2026-10-04T10:35:22.000Z",
    "syncs": [
      { "name": "persons", "status": "SUCCESS", "last_sync_at": "2026-10-04T10:35:20.000Z" },
      { "name": "organizations", "status": "SUCCESS", "last_sync_at": "2026-10-04T10:34:58.000Z" },
      { "name": "deals", "status": "SUCCESS", "last_sync_at": "2026-10-04T10:35:02.000Z" },
      { "name": "activities", "status": "SUCCESS", "last_sync_at": "2026-10-04T10:35:18.000Z" }
    ]
  },
  "meta": {
    "request_id": "req_def456",
    "timestamp": "2026-10-04T10:40:00.000Z"
  }
}

A freshly connected account that hasn’t run its first sync yet returns connected: false with an empty sync list — it will flip to connected on the next sync pass:

Status response (not yet connected)

{
  "data": {
    "connected": false,
    "syncs": []
  },
  "meta": {
    "request_id": "req_ghi789",
    "timestamp": "2026-10-04T10:40:00.000Z"
  }
}

Step 3 — 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.

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.

Step 4 — 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.

Matched conversation — inbox context panel resolves to a Pipedrive person

{
  "contact_id": "ct_9k2m4n7p",
  "contact_name": "Alice Chen",
  "crm_match": {
    "provider": "pipedrive",
    "person_id": 4281,
    "organization": {
      "id": 312,
      "name": "Acme Corp",
      "address": "123 Main St, San Francisco, CA"
    },
    "open_deals": [
      {
        "id": 871,
        "title": "Q4 Expansion",
        "value": 24000,
        "currency": "USD",
        "stage": "Proposal sent",
        "expected_close_date": "2026-11-15"
      },
      {
        "id": 904,
        "title": "Annual renewal",
        "value": 18500,
        "currency": "USD",
        "stage": "Negotiation",
        "expected_close_date": "2026-12-01"
      }
    ]
  }
}

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

Unmatched conversation branch

When a conversation arrives and the contact does not yet resolve to a Pipedrive person (the phone or email on the Pipedrive side is blank, or the sync hasn’t run yet), the inbox panel shows no CRM context:

Unmatched conversation — no Pipedrive link

{
  "contact_id": "ct_5r8t1w3q",
  "contact_name": "Bob Martinez",
  "crm_match": null
}

The conversation routes through Orbit’s normal inbound path without interruption. As soon as the Pipedrive admin fills in the phone or email on Bob’s Person record and the next scheduled sync runs, the link is established. Write-back that was deferred during the unmatched window catches up on the next retry cycle.

Step 5 — 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.

Activity write-back payload

When an AI agent resolves a conversation, it posts an activity to the matched Pipedrive person. The person_id field links the activity to the Pipedrive record; deal_id links it to an open deal when the conversation context includes deal intent:

AI agent posts an activity to Pipedrive

{
  "action": "create_activity",
  "provider": "pipedrive",
  "payload": {
    "person_id": 4281,
    "deal_id": 871,
    "subject": "AI agent — conversation with Alice Chen (order intent)",
    "type": "call",
    "done": true,
    "due_date": "2026-10-04",
    "due_time": "14:30",
    "note": "Alice confirmed the Q4 expansion order over SMS. Order intent detected — deal should move to 'Contract review' stage. Full transcript attached to conversation."
  }
}

Note write-back payload

Agents also log notes directly onto the person or deal timeline — useful for summarising multi-turn conversations where the outcome is diagnostic rather than a discrete activity:

AI agent posts a note to a Pipedrive deal

{
  "action": "create_note",
  "provider": "pipedrive",
  "payload": {
    "person_id": 4281,
    "deal_id": 871,
    "content": "Oct 4 follow-up: Alice asked about SLA terms on the Q4 expansion. Agent clarified the 99.95% uptime SLA and 4-hour response window. Alice indicated she will review and respond by EOW. No action needed until her reply."
  }
}

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.

Step 6 — 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. Use the type and done fields on the created activity to branch:

Branch on type: type: "call" fires your “call follow-up” workflow; type: "meeting" fires your “meeting booked” workflow. The agent sets the type based on the conversation channel.
Branch on done: done: true means the activity is complete — the conversation resolved. done: false means the conversation was handed back to a human for follow-up, and the activity is open on the rep’s Pipedrive task list.
Branch on due_date: the activity’s due date is the date the conversation happened. Use it to trigger a follow-up Automation that fires on due_date + 1 day.

Your Pipedrive admin decides what the Automation 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 own organization’s configuration, built by your own Pipedrive admin.

Step 7 — 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.

Integrations API reference — endpoint map for the connect/sync/status surface.
HubSpot & Salesforce guide — the same junction pattern for the other CRM providers, including their webhook receivers.
Identity resolution — how Orbit decides an inbound event links to an existing contact.

WhatsApp

Developer console

Contact center

Guides

Messaging Controls

Audience & Support Tools

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

Connect Pipedrive end to end

What you’ll set up

Step 1 — Connect via OAuth (admin only)

Step 2 — Confirm the connection worked

Step 3 — What syncs inbound

Step 4 — Match conversations to Pipedrive records

Unmatched conversation branch

Step 5 — AI-agent write-back

Activity write-back payload

Note write-back payload

Step 6 — Build on created activities with Pipedrive Automations

Step 7 — Troubleshooting common issues

​Connect Pipedrive end to end

​What you’ll set up

​Step 1 — Connect via OAuth (admin only)

​Step 2 — Confirm the connection worked

​Step 3 — What syncs inbound

​Step 4 — Match conversations to Pipedrive records

​Unmatched conversation branch

​Step 5 — AI-agent write-back

​Activity write-back payload

​Note write-back payload

​Step 6 — Build on created activities with Pipedrive Automations

​Step 7 — Troubleshooting common issues

​Related reading

Connect Pipedrive end to end

What you’ll set up

Step 1 — Connect via OAuth (admin only)

Step 2 — Confirm the connection worked

Step 3 — What syncs inbound

Step 4 — Match conversations to Pipedrive records

Unmatched conversation branch

Step 5 — AI-agent write-back

Activity write-back payload

Note write-back payload

Step 6 — Build on created activities with Pipedrive Automations

Step 7 — Troubleshooting common issues

Related reading