Connecting Revial to Pipedrive

Revial connects to Pipedrive as a Pipedrive Marketplace OAuth app. There is no API token to paste, no service account to provision, and no permission set to author. One person authorises the app once; Revial then holds a refresh token bound to that person's Pipedrive account and company. There is no credential to rotate afterwards and no ongoing administrative task.

Because Revial acts as that person, the connection sees exactly what they see. That single fact decides the scope of the integration, and section 2 covers it in full. It also means the only scoping decision available to you is who authorises — Pipedrive has no mechanism for granting an app a narrower view than its user's, so there is no role to trim.

1. What you need to determine before connecting

Two decisions are yours, and both are settled by choosing who clicks Connect.

1.1 Who authorises the connection

What to determine: which Pipedrive user account will authorise the app.

What it decides: everything Revial can see and everything Revial can write. Revial calls the Pipedrive API with that user's token, so it sees exactly the deals, persons and organizations that user sees in the Pipedrive UI, and writes as that user.

How to choose:

• If Revial should cover the whole pipeline, authorise with an admin account or any account with company-wide visibility.
• If Revial should be limited to a subset of the pipeline, authorise with a user whose Pipedrive visibility groups and permission set already restrict them to that subset. This is the only scoping mechanism available.

We recommend a dedicated, named integration user rather than an individual salesperson's account — not for security reasons, but for continuity. If a salesperson leaves and their Pipedrive account is deactivated, the connection stops and must be re-authorised by someone else.

1.2 Whether you use custom fields for meeting notes

Where to find it: ask whoever owns your Pipedrive configuration whether meeting summaries or transcripts are expected to land in a specific custom field on the deal, person or organization, rather than as an ordinary Pipedrive note.

What to determine: if so, the entity (deal / person / organization) and the custom field key.

What it decides: whether we configure field mapping for your connection. Revial can read your available fields and write into a nominated one. No schema change is needed on your side — the field must already exist.

Summary — please have these to hand

2. Important: OAuth scopes cannot separate B2B from B2C

If your reason for reading this closely is that one Pipedrive company holds both business and consumer records, please read this section before connecting.

A Pipedrive OAuth scope controls which endpoints an app may call and whether it may read or write. It does not filter rows. Granting persons:read grants read on every person the authorising user can see. There is no scope, and no combination of scopes, that says "only these deals".

Row-level restriction in Pipedrive comes from the user's own permissions: their permission set and their visibility groups. Since Revial acts as that user, those restrictions do carry through to the integration — but they are inherited, not configured for Revial.

Which case applies to you?

In case C, Revial only reads and writes records it has matched to an actual meeting attendee, so consumer records are not touched unless a consumer attends a tracked sales meeting. We want to be precise about what that is: it is a behavioural property of how the product works, not a restriction Pipedrive enforces. If your governance requires platform-level enforcement, case C needs a visibility-group restructure, and we would rather tell you that plainly than let a scope list imply a guarantee it cannot make.

3. Connecting

Performed by the Pipedrive user chosen in section 1.1, who must also be an Admin or Owner in Revial on a Medium or Sales plan.

1. In Revial, go to Organization Settings → CRM.
2. Select Connect with Pipedrive. You are redirected to Pipedrive.
3. Sign in as the account chosen in section 1.1 if you are not already. If a different account is already signed in, sign out first — the authorisation silently binds to whoever is signed in, and this is the most common mistake.
4. Review the requested scopes (section 4) and select Allow and Install.
5. You are returned to Revial, which shows Connected and the Pipedrive email the connection is bound to. Check that email — it is your confirmation that the right account authorised.

Revial validates the token by calling GET /api/v1/users/me before storing anything, so a failed authorisation is rejected immediately rather than surfacing later as a broken sync.

Revial holds one CRM connection per organization. If your organization already has a CRM connected, that connection must be removed before Pipedrive can be connected — the attempt is rejected rather than silently replacing it.

Whether an ordinary user can complete step 4 depends on your Pipedrive plan and settings — some companies restrict Marketplace app installation to admins. If the authorising user sees no Allow and Install button, an admin must either install the app or lift that restriction.

4. The scopes Revial requests

These are fixed by the Marketplace app and are not configurable per customer. Pipedrive presents them at the consent screen.

Notes are created through the deals/persons/organizations scopes above; Pipedrive has no separate notes scope.

Three scopes are enabled but unused. products:read, products:write and activities:write are on the app registration, but the Pipedrive sync calls no products endpoint and creates no activities — activity write-back is not implemented for Pipedrive. They are present on the app definition rather than because the integration exercises them. If that is a blocker for your review, tell us: they can be removed from the app registration, and we will confirm in writing.

The scope list you see at consent is set by the app registration, not by Revial's request. Revial does not pass a scope parameter when it sends you to Pipedrive, so what Pipedrive shows and grants is exactly what is enabled on the Marketplace app — the same list for every customer. There is no per-customer scope narrowing.

The write scopes are broader than what Revial does with them. Pipedrive has no field-level scope: deals:write permits updating any field on any visible deal, not only the one field Revial is configured to write. Revial writes notes and at most the specific custom fields you nominate — but that boundary is enforced by the software, not by the scope. If you need platform-level enforcement, the lever is the authorising user's permission set, not the scope list.

5. What Revial reads and writes

Reads — on the sync path:

After the first full sync, subsequent syncs are incremental: Revial passes updated_since and only pulls records changed since the last run. Records Pipedrive flags as deleted are detected on the same pass and removed from Revial's copy, so a deletion in Pipedrive propagates rather than leaving an orphan.

Writes:

Those are the only two writes. Revial does not create Pipedrive activities, does not add deal participants, and does not modify the standard fields on a deal, person or organization.

Some sub-resource fetches fail quietly. If reading a deal's participants or a pipeline's stages fails, Revial logs it and continues, so the sync reports success with that piece of data missing rather than raising an error. If attendee-to-deal matching or stage information looks incomplete after a sync, tell us — it is worth checking the logs rather than assuming the data is absent in Pipedrive.

Notes are attributed to the authorising user, because that is whose token makes the call. Revial does not set a separate owner on the note to attribute it to the individual meeting owner. If several sellers' meetings sync through one connection, every resulting note in Pipedrive shows the authorising user as its author. This is a real limitation rather than a configuration mistake — if per-seller attribution in Pipedrive matters to you, raise it with us.

6. Custom field mapping

Some organizations want meeting summaries or transcripts in a named custom field rather than as a free note. Revial supports this through configuration only.

Give us the entity (deal, person or organization) and the field key. Revial can list the available fields on your connection — including custom ones — so you do not need to hunt for the key yourself.

The field must already exist. Revial does not create fields, and does not modify your Pipedrive schema.

If a batch field update fails, Revial retries each field individually and reports which ones failed, rather than discarding the whole write.

7. What Revial deliberately does not do

Revial has no delete capability on any Pipedrive entity. It does not create or modify custom fields, does not change pipelines or stages, does not alter user permissions, and does not touch company settings.

The read scopes it holds are limited to the entities listed in section 5. Notably, Revial requests no mail scope — it does not read the content of your Pipedrive email sync, and the integration is deliberately built to avoid the mail:full requirement. It does read the last_incoming_mail_time and last_outgoing_mail_time timestamps that Pipedrive maintains on the standard person record, which it uses to judge whether a deal has gone quiet. Timestamps only — never subjects, bodies or recipients.

Be clear about what enforces each of these. The boundaries above rest on what the software does, not on a Pipedrive permission — the write scopes in section 4 would technically permit more. The one boundary Pipedrive itself enforces is the authorising user's visibility.

8. Credentials, expiry and revoking access

Access tokens last 60 minutes and Revial refreshes them automatically. Refresh tokens rotate on each refresh and do not expire on a fixed schedule. There is no rotation task for you.

A refresh token stops working when:

• the authorising user's Pipedrive account is deactivated or deleted;
• the app is uninstalled from your Pipedrive Marketplace;
• Pipedrive invalidates it.

Revial distinguishes a revoked or invalid refresh token from a temporary outage and reports it as a connection that needs re-authorising, rather than retrying silently.

To revoke Revial's access: uninstall the Revial app from Pipedrive Marketplace → Installed apps, or deactivate the authorising user. Either takes effect immediately.

Disconnecting inside Revial (Organization Settings → CRM → Disconnect) stops all syncing, deletes Revial's synced copy of your CRM data, and drops the stored credentials.

Notes and field values Revial previously wrote into Pipedrive stay there; a disconnect removes nothing from your CRM.

9. Verifying the connection

We suggest verifying in this order, as each step isolates a different scope.

1. The connection is accepted, and the email shown is the intended account. Confirms the token is valid and users:read works — and, more importantly, that the right person authorised.
2. The initial sync populates organizations, persons and deals. Confirms the read scopes and the authorising user's visibility.
3. Check that a deal shows the correct pipeline stage. Confirms pipelines:read.
4. Push a test meeting note to a known deal. Confirms note creation.
5. If you use field mapping, check the nominated field was written. Confirms the write scope on that entity.
6. For case A in section 2, confirm a consumer record is not present in the synced data. This is the check that proves the authorising user's visibility restriction actually holds.

10. Troubleshooting

11. Questions we cannot answer for you

Please raise these with us before connecting rather than after:

• Your consumer and business records are separated only by a field value (case C).
• You need per-seller attribution on notes written into Pipedrive.
• You need Revial restricted to specific pipelines.
• Your review requires written confirmation on the products scopes in section 4.