Conversion HubSpot Integration Guide

🚀 What You Can Do With This Integration

Once connected, Conversion enables your business to sync and manage the following HubSpot data directly from your dashboard:

✅ Contacts
✅ Leads
✅ Lists
✅ Companies
✅ Deals
✅ Custom Objects

🔐 Connecting Your HubSpot Account (OAuth Flow)

Start the connection
When you click “Connect HubSpot” in your Conversion dashboard:
- The frontend will call:
  GET /v1/businesses/:businessId/oauth/hubspot?redirectUrl={yourReturnUrl}
- You'll be redirected to HubSpot to log in and grant permissions.
Grant access on HubSpot
You’ll be prompted to accept access to scopes like reading/writing contacts, companies, and deals. (Full list below.)
Finish setup
After you accept, you’ll be redirected back to your original redirectUrl. At this point, your account is fully linked and ready to use.

🔍 Supported Permissions (Scopes)

When connecting to HubSpot, you’ll be asked to approve access to:

jsonCopyEdit[ "crm.objects.contacts.read", "crm.objects.contacts.write", "crm.lists.read", "crm.lists.write", "crm.objects.companies.read", "crm.objects.companies.write", "crm.objects.deals.read", "crm.objects.deals.write", "crm.objects.custom.read", "crm.objects.custom.write", "crm.objects.leads.read", "crm.objects.leads.write" ]

These allow us to safely read/write data you select within Conversion.

📬 Using the Integration

Once your account is connected, the frontend has access to new buttons, actions, and forms powered by these endpoints. Here's how it works:

✨ Syncing Contacts

View contacts:
Calls GET /v1/businesses/:businessId/oauth/hubspot/contacts
Displays contacts in the dashboard with properties like name, email, and history.
Create/Update contacts:
Calls POST /v1/businesses/:businessId/oauth/hubspot/contacts
Form-based input to sync your local CRM with HubSpot.

🧲 Managing Leads

Add leads in bulk:
POST /v1/businesses/:businessId/oauth/hubspot/leads
Edit or update leads:
PATCH /v1/businesses/:businessId/oauth/hubspot/leads
View leads:
GET /v1/businesses/:businessId/oauth/hubspot/leads
Displayed in a lead table UI with full CRM syncing.

🏢 Sync Companies

You can batch-create and sync company data, including properties like name, domain, industry, and more.

Create: POST /v1/businesses/:businessId/oauth/hubspot/companies
Read: GET .../companies
Update: PATCH .../companies

💼 Track Deals

Connect deals from your sales pipeline directly to contacts/companies.

Create: POST /v1/businesses/:businessId/oauth/hubspot/deals
Update: PATCH .../deals
View: GET .../deals

📚 Lists

Use this to group contacts or leads into marketing segments.

Create a new list: POST /v1/businesses/:businessId/oauth/hubspot/lists
Fetch your lists: GET /v1/businesses/:businessId/oauth/hubspot/lists

Lists can be snapshot, dynamic, or manually curated.

⚙️ Custom Objects

Create custom CRM objects that reflect your unique business needs (like "Projects", "Invoices", or "Campaigns").

Create: POST /v1/businesses/:businessId/oauth/hubspot/custom-object
Get one: GET /v1/businesses/:businessId/oauth/hubspot/custom-object
Get all schemas: GET /v1/businesses/:businessId/oauth/hubspot/all-custom-objects

🧑‍💻 As a Frontend Developer…

You’ll typically:

Trigger OAuth from your UI via a button click.
Handle redirect behavior after OAuth callback.
Display data (contacts, deals, etc.) using the corresponding GET endpoints.
Submit data (create/update forms) using POST/PATCH endpoints.
Use loading states, error handling, and success toasts appropriately.

📦 API Behavior Notes

All endpoints are businessId scoped.
HubSpot connections are saved as a reusable "Bridge" in our system.
Object syncing is batch-optimized, reducing calls and improving speed.
Data is structured and typed — ideal for strict TypeScript consumption.

📚 Resources

Getting started with Conversion

Hubspot Integration

Salesforce Integration

​🚀 What You Can Do With This Integration