How a Company Admin connects HubSpot CRM to Ricavi: the connection flow, which objects and properties are needed, what Ricavi writes back, and the controls available to you.

Who sets this up: the Company Admin. Sellers and Selling Managers do not need to do anything. The CRM connection appears to them as a read-only card during onboarding showing the connected provider name.

How long it takes: around 5–10 minutes, most of which is field mapping.

One CRM at a time

Ricavi supports HubSpot, Salesforce and Microsoft Dynamics. Only one CRM can be active per organisation at any time. Switching providers means disconnecting the current CRM first.

Before you begin

You are signed in to Ricavi as a Company Admin.
You have HubSpot credentials with permission to authorise a third-party application, and to read and write the objects listed in section 3.
You know which objects you want Ricavi to sync. Contacts, Deals and Activities can each be included or left out.
You have decided which properties should be eligible for AI-suggested updates (the whitelist) and which should never be touched (the blacklist).

1. Connect the CRM

Go to Company Configuration in Ricavi. You can also do this during onboarding; the flow is identical.

Open Company Configuration and start the CRM connection.
Select HubSpot as your CRM provider.
Complete the OAuth 2.0 authorisation prompt and sign in with your HubSpot account.
Configure field mapping (see section 4).
Select which CRM objects to sync (see section 2).
Confirm. The connection status appears in the Company Configuration panel.

Once connected, the integration shows one of three states:

Status	What it means
Active	The connection is healthy and syncing.
Error	Something has failed. Open the sync log to see the specific errors.
Disconnected	No CRM is connected. Agentic action types that need a CRM will not be shown to Sellers.

2. Choose which objects to sync

Ricavi syncs with three core HubSpot objects. Each one is selected during setup.

Object	What Ricavi uses it for	Direction
Contacts	Buyer identification, stakeholder mapping, meeting attendee matching, buying committee tracking, single-threaded risk detection	Read + Write
Deals	Deal health scoring, pipeline management, forecasting, pre-call preparation, post-call sync, agentic actions	Read + Write
Engagements (Activities)	Call logging, follow-up task creation, activity tracking for stalled deal detection, engagement monitoring	Read + Write

Leaving one out

Skipping an object limits related features. Without Activities, for example, Ricavi cannot detect stalled deals, because that trigger relies on activity dates.

3. Properties Ricavi reads

These are the minimum properties Ricavi needs to deliver pre-call preparation, deal health scoring, pipeline views, forecasting and AI coaching context. Properties marked Recommended are optional, but leaving them out reduces the quality of the output.

3.1 Deal properties

HubSpot property	What it powers	Required
`dealname`	Deal identification across dashboard, pipeline, Action Hub and briefings	Yes
`associatedcompanyid`	Pre-call preparation (auto-populates the Account field), deal grouping by company	Yes
`dealstage`	Pipeline Kanban view, deal stage tracking, stagnant stage detection (30-day trigger)	Yes
`amount`	Pipeline value totals, forecast calculations, action prioritisation by deal value	Yes
`closedate`	Close Date Passed trigger, Close Date at Risk alert (7-day window), forecast views	Yes
`hubspot_owner_id`	Rep assignment, manager pipeline filtering, team analytics	Yes
`hs_deal_stage_probability`	Baseline for AI forecast comparison, forecast delta calculations	Recommended
`hs_next_step`	Pre-call context, coaching chat awareness, action suggestions	Recommended
`hs_forecast_category`	Seller forecast view (High / Medium / Low mapping), forecast delta reporting	Recommended
`pipeline`	Pipeline identification when multiple pipelines exist	Recommended

3.2 Contact properties

HubSpot property	What it powers	Required
`firstname` / `lastname`	Meeting attendee identification, stakeholder mapping, coaching context	Yes
`email`	Meeting matching, follow-up email actions, attendee identification	Yes
`jobtitle`	Buying committee coverage scoring, EDM identification, stakeholder map	Yes
`associatedcompanyid`	Contact-to-deal association, single-threaded risk detection	Yes
`phone`	Call script actions, stalled deal revival (Step 3)	Recommended

3.3 Activity properties

HubSpot property	What it powers	Required
`hs_engagement_type`	Activity type classification (call, email, meeting, task)	Yes
`hs_timestamp`	Stalled deal detection (14-day inactivity trigger), timeline tracking	Yes
`hs_task_status`	Open vs completed task tracking, Action Hub log	Yes
`associations` (Deal)	Linking activities to deals for health scoring and stall detection	Yes
`hs_body_preview` / `hs_note_body`	AI context for coaching, pre-call preparation enrichment	Recommended

4. Configure field mapping

Field mapping tells Ricavi which HubSpot property corresponds to each Ricavi data point. You set this up during CRM setup and can revisit it at any time.

Setting	What it does
Property mapping	Maps each Ricavi data point to the corresponding HubSpot property.
Object selection	Chooses which CRM objects are synced: Contacts, Deals, Activities.
Property whitelisting	Only whitelisted properties are eligible for AI-suggested updates.
Property blacklisting	Blacklisted properties are never suggested for update, which gives you an extra layer of data governance.
Sync log	A full history of sync events, including errors, for monitoring and troubleshooting.

If a mapping is missing

Where no mapping exists for a given property, Ricavi saves the data as a note on the Deal record instead of discarding it. Nothing is lost, but it will not be reportable as structured data.

5. What Ricavi writes back

Ricavi writes to HubSpot under two conditions: post-call sync and agentic actions. No data is written automatically. Every write requires the Seller to review and approve it first.

5.1 Post-call sync

Data written	HubSpot target	Details
Deal Stage Change	`Deal.dealstage`	AI-suggested stage progression based on call content
Next Steps	`Deal.hs_next_step`	Extracted from call discussion, editable before sync
Call Log	Engagement (Call)	Call date, duration and participants, associated with the Deal
Contact / Stakeholder Updates	Contact properties	New contacts, or updated roles identified during the call
Methodology Field Responses	Deal (custom properties)	Captured from the transcript against the active methodology, e.g. MEDDPICC fields
Call Recording, Transcript & AI Summary	Note on Deal	Attached to the linked Deal record

When a call ends, Ricavi generates AI-suggested CRM updates. The Seller reviews, edits and approves each update before it is pushed.

5.2 Deal Health fields

Ricavi creates nine custom property sets on the Deal object, auto-populated from call transcripts, emails and meeting notes. Two summary properties are also written back:

Custom property	Type	Description
Deal Health Score	Number (0–100)	Composite score from the nine-category model below
Deal Health Status	Enumeration	Green (80–100), Amber (60–79), Red (below 60)

The nine categories that feed the score:

Category	Weight	Critical gate
1. Problem Statement Quality	15 pts	Yes
2. Discovery Brief / Post-Meeting Notes	15 pts	Yes
3. Business Impact & Business Case Evidence	20 pts	Yes
4. Buying Committee Coverage	15 pts	No
5. Internal "Project" Exists	10 pts	No
6. Proposal Process Quality	10 pts	No
7. Commercial & Budget Alignment	10 pts	No
8. Procurement / Vendor Path Clarity	5 pts	No
9. Mutual Action Plan to Decision	10 pts	No

How scoring works

Each category is scored 0 = Missing, 1 = Partial, 2 = Complete and validated with the buyer.

If any of categories 1, 2 or 3 scores 0, the deal is marked Red regardless of its total score. This shows as "Critical Gate Failed".

5.3 Agentic actions

Action type	HubSpot write	Details
Update Deal Stage	`Deal.dealstage`	AI-recommended stage with a plain-language reason
Update CRM Records	Deal / Contact properties	Log Call, Add Notes or Update Properties, with a preview
Create Follow-Up Task	Engagement (Task)	Task name, due date, priority, notes
Send Follow-Up Email	Engagement (Email, logged)	Email sent via the connected email integration and logged in HubSpot
Create / Update Contact	Contact	New contact creation or existing contact property updates
Create / Update Company	Company	Company record creation or updates
Create / Update Deal	Deal	Deal record creation or updates
Add Stakeholder	Contact association on Deal	New stakeholder associated to the deal

Safeguard

Company Admins can whitelist and blacklist specific CRM properties for AI-suggested updates. Only whitelisted properties are eligible for suggestion; blacklisted properties are never suggested.

Action types that require a CRM connection are hidden entirely when no CRM is connected.

6. Deal health triggers

Ricavi monitors the deal data it reads from HubSpot and raises alerts against the conditions below. All thresholds are configurable by the Company Admin.

Trigger	Condition	Default	What happens
At Risk	Deal Health Score drops below 60	n/a	Deal card turns Red, Morning Briefing alert, agentic actions raised in Seller and Manager Action Hubs
Watch	Score drops from Green to Amber	n/a	Watch flag, listed under "Deals to Watch" in the Morning Briefing
Stalled Deal	No activity on the deal	14 days	Revival Plan generated (Email, LinkedIn, Call Script)
Stagnant Stage	Stage unchanged	30 days	Agentic action to progress the deal
Close Date Passed	Close date has passed	n/a	Agentic action to update and re-forecast
Close Date at Risk	Close date within X days and deal is Amber or Red	7 days	Flagged in the Morning Briefing and on the Manager dashboard
EDM Engagement Gap	No contact with the Economic Decision Maker	21 days	Agentic action to re-engage the EDM
Single-Threaded Risk	Only one contact on the deal	n/a	Risk flag plus agentic action to request introductions

7. Governance and safeguards

No automated writes. Every CRM update requires explicit Seller approval.
Admin-controlled scope. The Company Admin controls property whitelisting and blacklisting, object sync selection, and which agentic action types are available per user or team.
Full audit trail. The sync log holds a complete history of sync events, including errors.
Cross-tenant oversight. The Super Admin monitors integration health and data audit trails across tenants.

8. Troubleshooting

Symptom	What to check
Status shows Error	Open the sync log in Company Configuration. It lists the individual sync events and the errors against them.
Agentic actions are missing for Sellers	Action types that require a CRM are not displayed when no CRM is connected. Confirm the integration status is Active.
Data is landing as notes instead of properties	No mapping exists for that property. Add the mapping in field mapping configuration.
A field is never suggested for update	Check whether it has been blacklisted, or simply not whitelisted. Only whitelisted properties are eligible.
Stalled deals are not being detected	Stall detection relies on activity dates. Confirm Activities are included in the synced objects.
Need to start again	The Company Admin can disconnect the CRM connection at any time from Company Configuration.

Common questions

Question	Answer
Can we run two CRMs at once?	No. One CRM is active per organisation at any time.
Do Sellers need to connect anything?	No. CRM connection is the Company Admin's responsibility. Sellers see a read-only card showing the connected provider.
Will Ricavi change our data without asking?	No. Every write, post-call sync and agentic actions alike, requires the Seller to review and approve it.
Can Sellers edit what Ricavi suggests?	Yes. Suggested updates are editable before they are approved and pushed.
Can we stop Ricavi touching sensitive fields?	Yes. Blacklist them. Blacklisted properties are never suggested for update.
Can we change the health score thresholds?	Yes. All trigger thresholds are configurable by the Company Admin.

Connecting HubSpot to Ricavi