HubSpot Integration

Sellestial connects directly to HubSpot to read and write contact, company, and deal data.

Connection Setup

Initial Connection

1. Navigate to Settings → General
2. Click Connect HubSpot (or Reconnect HubSpot)
3. HubSpot OAuth flow opens in new window
4. Select your HubSpot account
5. Review requested permissions
6. Click Grant Access
7. Redirect back to Sellestial
8. Connection status updates to “Connected”

Reconnecting

When to reconnect

• Adding new Sellestial features (may need new scopes)
• After HubSpot updates
• When experiencing auth errors
• Proactively every 3-6 months

How to reconnect:

1. Settings → General
2. Click Reconnect HubSpot
3. Complete OAuth flow again
4. Grant any new requested scopes

Required Scopes

Sellestial requests these HubSpot permissions:

Core Permissions (Required)

Contacts:

• crm.objects.contacts.read — Read contact data
• crm.objects.contacts.write — Create/update contacts

Companies:

• crm.objects.companies.read — Read company data
• crm.objects.companies.write — Create/update companies

Properties:

• crm.schemas.contacts.read — Read contact properties schema
• crm.schemas.companies.read — Read company properties schema
• crm.schemas.contacts.write — Create custom contact properties
• crm.schemas.companies.write — Create custom company properties

Lists:

• crm.lists.read — Access HubSpot lists as pipeline sources

Optional Permissions

Deals:

• crm.objects.deals.read — Read deal data
• crm.objects.deals.write — Create/update deals

Tasks & Notes:

• crm.objects.tasks.write — Create tasks
• crm.objects.notes.write — Create notes

Sequences:

• automation.actions.sequences.write — Add contacts to HubSpot sequences

Grant All Permissions

For full functionality, grant all requested scopes. You can review and revoke permissions anytime in HubSpot settings.

What Sellestial Can Access

Read Operations

Contact Data:

• Standard properties (name, email, phone, etc.)
• Custom properties
• Associated company
• Lifecycle stage
• Deal associations
• Activity history

Company Data:

• Standard properties (name, domain, industry, etc.)
• Custom properties
• Associated contacts
• Deal associations
• Notes and tasks

Deal Data:

• Standard properties (amount, stage, close date)
• Custom properties
• Associated contacts and companies

Lists:

• List membership
• List names and IDs
• Static and active lists

Write Operations

Contact Updates:

• Create new contacts
• Update existing contact properties
• Merge duplicate contacts (via pipelines)
• Associate with companies
• Add to lists

Company Updates:

• Create new companies
• Update existing company properties
• Merge duplicate companies (via pipelines)
• Associate with contacts

Tasks & Notes:

• Create tasks for follow-up
• Add notes to timeline
• Set due dates and priorities

Sequences:

• Add contacts to HubSpot sequences (if scope granted)

Custom Properties

Sellestial creates custom properties with the sellestial_ prefix.

Common Properties

Contacts:

• sellestial_mail_domain_check — Email validation status
• sellestial_real_person_check — Authenticity classification
• sellestial_employment_status — Job change status
• sellestial_email_discovery_status — Email finder results

Companies:

• sellestial_duplicate_status — Deduplication status

Sequences:

• sellestial_email_1_body — Generated email step 1
• sellestial_email_1_subject — Email subject step 1
• (and so on for additional steps)

Property Management

Auto-Created: Pipelines automatically create properties as needed

Naming Convention: sellestial_[pipeline]_[field]

Data Types:

• Single-line text
• Multi-line text
• Number
• Date
• Enumeration (dropdown)

Field Mapping

How Mapping Works

Pipelines map enriched data to HubSpot properties:

Enrichment Field → CRM Field
---
firstname → firstname
lastname → lastname
jobtitle → jobtitle
country → country

Write Modes

Control how data updates existing values:

Always Overwrite:

Current: "USA"
Enriched: "United States"
Result: "United States" (replaced)

Write if Empty:

Current: (empty)
Enriched: "United States"
Result: "United States" (written)

Current: "USA"
Enriched: "United States"
Result: "USA" (unchanged)

Write if Not Modified by User:

Last modified by: ENRICHMENT
Enriched: "United States"
Result: "United States" (updated)

Last modified by: USER
Enriched: "United States"
Result: (unchanged, respects user edit)

Skip:

Never writes, regardless of current value

Checking Modification Source

For “Write if Not Modified by User” mode, Sellestial checks HubSpot property history:

Source Types:

• CRM_UI — User entered (don’t overwrite)
• IMPORT — User uploaded (don’t overwrite)
• ENRICHMENT — System enriched (safe to overwrite)
• API — Integration update (safe to overwrite)
• CALCULATED — System calculated (safe to overwrite)

Lists as Sources

HubSpot lists are the primary input source for pipelines.

Supported List Types

Static Lists:

• Fixed membership
• Manually managed
• Contacts added/removed explicitly

Active Lists:

• Dynamic membership
• Filter-based
• Auto-updates based on criteria

Use Active Lists

Active lists automatically include new matching records, perfect for continuous processing pipelines.

Common List Patterns

New Records:

"Contacts created in last 7 days"
- Create date is within last 7 days

Missing Data:

"Contacts without email"
- Email is unknown

Data Quality:

"Invalid email domains"
- sellestial_mail_domain_check is NO_MX_RECORD or INVALID_DOMAIN

Segmentation:

"Enterprise contacts"
- Company employee count is greater than 1000
- Job title contains "VP" or "Director" or "C-level"

Record Linking

Throughout Sellestial, records link directly to HubSpot.

External Link Icon: Click the 🔗 icon next to any contact/company name to open the record in HubSpot.

Direct URLs: Sellestial constructs HubSpot deep links:

https://app.hubspot.com/contacts/[portal-id]/contact/[contact-id]
https://app.hubspot.com/contacts/[portal-id]/company/[company-id]

Rate Limits

HubSpot API Limits

Standard (default):

• 100 requests per 10 seconds
• Burst limit: 150 requests

Professional:

• 120 requests per 10 seconds
• Burst limit: 180 requests

Enterprise:

• 150 requests per 10 seconds
• Burst limit: 200 requests

Sellestial Management

Sellestial automatically handles rate limiting:

• ✅ Requests queued when approaching limits
• ✅ Automatic retry with exponential backoff
• ✅ Batch operations where possible
• ✅ No action needed from you

Troubleshooting

Connection Issues

Problem: Status shows “Disconnected”

Solutions:

1. Click Reconnect HubSpot
2. Complete OAuth flow
3. Grant all requested scopes
4. If still failing:
   • Check HubSpot account status
   • Verify admin permissions in HubSpot
   • Try different browser
   • Clear browser cache
   • Contact support

Missing Scopes

Problem: Features unavailable or errors like “Missing scope: contacts.write”

Solutions:

1. Go to Settings → General
2. Note current scope count
3. Click Reconnect HubSpot
4. Grant all requested scopes
5. Verify scope count increased
6. Retry operation

Property Write Failures

Problem: Enrichment runs but properties not updating

Check:

1. Write mode configuration
2. Property exists in HubSpot
3. Property type matches data
4. Field mapping correct
5. Permissions granted

Solutions:

• Review pipeline Settings → Field Mapping
• Check execution logs for errors
• Verify property types in HubSpot
• Ensure write permissions granted

Duplicate Records Created

Problem: Multiple records for same person/company

Causes:

• Matching logic too loose
• Missing deduplication rules
• Concurrent processing

Solutions:

1. Set up Deduplication rules
2. Use merge pipelines from Marketplace
3. Adjust pipeline input sources

Performance Issues

Problem: Pipeline processing slowly

Possible causes:

• Large HubSpot lists
• Complex property calculations
• Rate limit throttling

Solutions:

• Process smaller batches
• Use more targeted lists
• Adjust processing limits
• Review system status

Best Practices

Property Management

Naming:

• Use clear, descriptive names
• Follow conventions (e.g., sellestial_ prefix)
• Document custom properties

Organization:

• Group related properties
• Add help text for clarity
• Set appropriate field types

List Strategy

Segmentation:

• Create specific lists for each pipeline
• Use active lists for automation
• Document list criteria

Maintenance:

• Review list membership regularly
• Archive unused lists
• Update criteria as needed

Data Quality

Before Enrichment:

1. Run validation pipelines from Marketplace
2. Run quality assessment pipelines
3. Filter invalid records

After Enrichment:

1. Review success rates
2. Validate enriched data
3. Update lists based on results

Next Steps

• Data Sources — Available data providers
• Pipeline Kinds — Choose the right pipeline kind
• Best Practices — Optimization tips