Pipedrive technical integration guide
For Pipedrive administrators, security reviewers and IT — how Revial authenticates, the scopes and access it relies on, API consumption, failure behaviour and auditing.
This guide describes what Revial does inside your Pipedrive company, so you can approve, configure and later audit the integration. For connecting and the B2B/B2C scoping question see Connecting Revial to Pipedrive; for every field read and written see What Revial syncs with Pipedrive.
1. What you are approving
Revial connects as a Pipedrive Marketplace OAuth app using the Pipedrive API (v2 endpoints, plus v1 for notes, deal participants and the user check).
| Property | Value |
|---|---|
| Access model | Delegated — Revial acts as the Pipedrive user who authorised it |
| Protocol | OAuth 2.0 authorisation code |
| Scopes | Fixed on the Marketplace app (see Connecting, section 4) |
| Pipedrive admin rights | Not required by Revial; your company may restrict who can install apps |
| App-only access | None |
Everything Revial sees and writes is limited by the authorising user's permission set and visibility groups.
2. What your admin has to do
| Situation | What to do |
|---|---|
| Your company restricts Marketplace installs | Install the app as an admin, or allow the authorising user to install |
| You want a dedicated integration user | Create it with the visibility Revial should have, and have that user connect |
| You want Revial to write fields | Create the fields in Pipedrive, then map them in Revial |
| Consumer and business data share visibility | Read section 2 of the connection guide before connecting |
3. Authentication and token model
| Property | Value |
|---|---|
| Authorise endpoint | https://oauth.pipedrive.com/marketplace/oauth/authorize |
| Token endpoint | https://oauth.pipedrive.com/oauth/token (client authenticated with HTTP Basic) |
| Scope parameter | Not sent — Pipedrive grants the scopes set on the app |
| PKCE | Not used |
| API host | The api_domain Pipedrive returns with the token, stored per connection |
| Post-connect check | GET /api/v1/users/me |
| Token lifetime | As reported by Pipedrive (expires_in); refreshed when less than 35 minutes remain |
State. A random single-use state, valid for five minutes, bound to the Revial
user who started the flow; the callback re-checks the user's admin role.
Storage. Access and refresh tokens are encrypted at rest (AES-256-GCM). Revial also stores the API domain, the Pipedrive company ID and the authorising user's ID, name and email. The client secret stays on Revial's servers.
Refresh. Up to three attempts with a short backoff. If Pipedrive returns a new
refresh token, it is stored. A 401 or invalid_grant marks the connection as
needing re-authorisation and an organisation admin gets an in-app notification;
the hourly sync then skips it. If a rotated token cannot be stored, the connection
is also marked broken rather than continuing with a dead token.
Who may connect on the Revial side. An organisation owner or admin on a plan with the CRM integration; rate-limited. One Pipedrive connection per organisation; other CRMs can be connected alongside it. Connecting resets the connection's stored settings.
4. Scopes and what they are used for
| Revial needs to… | Scope |
|---|---|
| Read organizations, persons, deals, participants | organizations:read, persons:read, deals:read |
| Read pipelines and stages | pipelines:read |
| Read activities | activities:read |
| Check the authorising user | users:read (/users/me only) |
| Create notes; update mapped fields | deals:write, persons:write, organizations:write |
| Anything with products, or create activities | Not used |
Pipedrive has no field-level scope, so write scopes permit updating any field the user can edit. Revial only writes notes and the fields your admins map.
5. What Revial reads
Organizations, persons, deals (with participants), pipelines and stages, activities of all types, and notes. The authorising user is checked once at connect, and field definitions are read for the mapping screen. Details: What Revial syncs with Pipedrive.
Revial reads no email content, files, products, or your user list.
6. What Revial writes
| Operation | Endpoint | Details |
|---|---|---|
| Meeting summary | POST /api/v1/notes | One note per target, with content and one of deal_id, person_id, org_id |
| Mapped fields | PATCH /api/v2/{persons,organizations,deals}/{id} | Only fields your admins map |
Before a mapped write, Revial reads the record (GET /api/v2/{entity}/{id}) so it
can leave existing values alone. Revial never deletes anything and never
creates deals, persons, organizations or activities.
7. Field mappings
Configured by organisation admins and owners under Organization → CRM Settings → Property Mapping. Values are converted to the Pipedrive field type (numbers for monetary and numerical fields, text otherwise) and text is capped at 64 KB. A failed batch update is retried field by field and failures are reported.
Known issues: the organization field list currently shows team fields; and Pipedrive's v2 API may expect custom fields in a nested structure, which Revial does not yet send — if a mapped custom field is not updated, contact support.
8. Sync cadence and API consumption
- First sync — a full pull of each entity, 500 records per page, up to 50,000 records per endpoint.
- Later syncs — roughly every hour,
updated_sincethe previous sync, sorted by update time. - Order — organizations → persons → stages → deals → activities → notes, each as a separate job.
Deal participants are fetched one request per deal, on full and incremental syncs, so large pipelines mean many calls. Stages are fetched per pipeline.
Rate limits. The sync does not back off or read Pipedrive's rate-limit
headers: a failed request fails that step, which is retried by the job queue. A
rate-limit response while reading participants fails the deals step for that run.
Manual pushes from Revial retry up to three times and respect Retry-After.
Timeouts. 30 seconds per request.
Deletions. Records flagged deleted are removed on incremental syncs; a full sync does not filter them out.
Record cap. If an endpoint has more than 50,000 changed records in one run, the remainder is skipped and not picked up later.
9. Meeting-to-CRM matching
Revial links a meeting to Pipedrive records in this order, first match wins: direct IDs on the meeting; the open deal it is already linked to; attendee emails → persons → their deals (scored); organization by website or email domain; organization by name. Deal scoring favours open deals, the attendee being the deal's person, other attendees on the deal, title similarity, later stages and recency. Closed deals are excluded, and free-email domains are ignored for organization matching.
10. Security, limits and failure behaviour
- Least privilege: delegated access only; the authorising user's visibility is the hard boundary.
- Secrets: tokens encrypted at rest; client secret server-side only.
- Partial failures: a failure reading the first pipeline's stages, or deal participants, marks the sync partial instead of reporting success.
- Idempotent notes: a meeting's summary is written once per connection.
- Data storage: synced records and the raw API responses are stored in Revial and deleted when you disconnect.
11. Auditing and disconnecting
In Pipedrive: installed Marketplace apps show Revial; notes written by Revial are authored by the authorising user.
To disconnect:
- In Revial — Disconnect on the Pipedrive card. Revial deletes its synced copy, tokens and field mappings. It makes no revoke call to Pipedrive.
- In Pipedrive — uninstall the app or deactivate the authorising user. Revial's next refresh fails, the connection is flagged and syncing stops.
Neither removes notes or field values Revial already wrote.
12. Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Unexpected email on the card | Another Pipedrive account was signed in | Disconnect, sign out of Pipedrive, reconnect |
| Deals missing | Authorising user's visibility | Adjust visibility groups, or connect a user who sees them |
| Sync marked partial | Stages or participants could not be read | Check the user's access; the next sync retries |
| Mapped field not updated | Field type mismatch, or the custom-field issue in section 7 | Check the per-field failure; contact support |
| "CRM: Authentication expired" | App uninstalled or user deactivated | Connect again |
| Heavy API usage | First sync, or many deals (participants per deal) | Expected; later syncs track changes |
What Revial syncs with Pipedrive
For your Pipedrive administrator and whoever reviews the integration's data access — every Pipedrive field Revial reads, everything it writes back, and the known gaps.
Connecting Revial to Salesforce
OAuth sign-in, production and sandbox orgs, connected-app approval, and what to do when the connection is blocked.