ScaleboX connector

HubSpot OAuth Authorization

Authorization status of this HubSpot portal with CRM scopes.

Connect Portal

Connected Portal Hub ID

Portal Domain

Connected Outreach Teams / Accounts

All connected ScaleBox & GetSales teams are equal. Each team has its own dedicated inbound webhook URL.

Loading connected teams...

⚡ How to Set Up Inbound Webhooks in ScaleBox / GetSales

Copy the dedicated Webhook URL from your connected team card above and configure it in your outreach workspace settings.

Step 1: Open Settings
In ScaleBox, go to Settings → Webhooks → Add Webhook.

Step 2: Paste Webhook URL
Paste the URL from the team card above with your Hub ID and Team ID.

Step 3: Select Trigger Events
Check contact.created, contact.updated, and message.received.

➕ Connect Outreach Team / Account

Connect another ScaleBox or GetSales team by providing the domain, Team ID, and API key (JWT token).

App API Domain Detected: ScaleBox

App Team ID

App API Token / Key (JWT)

Owner Synchronization

Map outreach Agents from all connected ScaleBox & GetSales teams to Contact Owners (HubSpot).

Overwrite existing Contact Owner (HubSpot) if Agent changes

When enabled, if an outreach lead in ScaleBox is reassigned to another Agent, HubSpot's Contact Owner will be automatically updated to the newly mapped owner. When disabled (recommended), existing contact owners are preserved to protect ongoing sales activities.

Agent	Connected Team	ScaleBox / GetSales Agent UUID	Contact Owner (HubSpot)	Action
No Agent mappings configured yet. Click "🔄 Sync Agents from App".

Properties & Synchronization Mapping

Configure field mappings and synchronization rules for Contacts and Companies in HubSpot CRM.

Standard Contact Properties

Standard lead attributes. You can map them to native or custom HubSpot fields, toggle synchronization, and adjust overwrite rules.

Active	ScaleBox Field	Destination Type	HubSpot Property	HubSpot Property Label	Overwrite Policy
Loading field mappings...

Showing standard fields

System Properties

ScaleBox identifiers, message threads, SDR routing, and workflow metadata. HubSpot field names are locked to maintain integration integrity; overwrite policies can be adjusted below.

Status	ScaleBox Field	Destination Type	HubSpot Internal Name	HubSpot Property Label	Overwrite Policy
Loading system properties...

System properties active

🏢 Company Synchronization & Association

Automatically find or create companies in HubSpot and link outreach contacts as Primary company associations.

🏢 ⏸️

Company Synchronization is Disabled

When disabled, incoming outreach leads are synced to HubSpot as standalone contacts without company associations. Zero company API calls or searches are performed in HubSpot.

Active	ScaleBox Field	Destination Type	HubSpot Property	HubSpot Property Label	Overwrite Policy
Loading company mappings...

Status	ScaleBox Field	Destination Type	HubSpot Internal Name	HubSpot Property Label	Overwrite Policy
Loading system properties...

Custom Channels Quota & Plan

Two-way LinkedIn messaging directly inside HubSpot Conversations Inbox with dynamic SDR slots.

Current Plan Tier

LIFETIME VIP Active

Duration: 99 Years (Unlimited data flow)

Channel Slots Quota

10 Available

0 / 10 slots connected

HubSpot Inbox Optimization

HubSpot Conversations Inbox supports up to 10 channel accounts per inbox without UI clutter.

💡 Each slot can be dynamically switched to another SDR at any time without losing chat history.

Connected Channel Slots

Each slot maps a HubSpot Custom Channel in Conversations Inbox to an outreach SDR profile.

Slot #	HubSpot Channel Name	HubSpot Inbox	Assigned ScaleBox SDR	Team	Status	Actions
Loading channel slots...

Message Delivery Statuses (4-Stage Pipeline)

Live audit of LinkedIn messages sent and received with real-time stage tracking.

Date & Time	Channel / SDR	Lead UUID	Direction	Message Text	Delivery Status
No messages sent or received yet.

Polling Synchronization & Historical Depth

Synchronize contacts and leads from all connected ScaleBox & GetSales teams with HubSpot CRM.

Run Manual Synchronization

Trigger an on-demand pull of outreach leads. Choose whether to sync recent changes or pull historical leads updated since a specific date.

Sync Depth / Historical Window

💡

How Synchronization Works:

Both scheduled 10-minute background syncs and manual sync runs query all connected ScaleBox & GetSales teams. Newly created and updated outreach leads are deduplicated by ScaleBox UUID, Email, and Phone, then synced into HubSpot CRM with all 38 mapped properties.

To inspect the live stream of processed leads, deduplication decisions, and property updates, visit the 📜 Integration Logs tab.

Integration Audit & Sync Logs

Detailed log of all incoming ScaleBox events, deduplication results, and HubSpot CRM operations.

Time & Event	Contact & Team	ScaleBox UUID	HubSpot Contact	Status	Details
Loading logs...

Integration Help Center & Documentation

Technical reference for connection setup, webhooks, field mapping, data types, allowed enumeration values, and synchronization architecture.

Platform Version: 2025.2+

🔌 1. HubSpot OAuth 2.0 Authorization

Authorization

OAuth 2.0 Standard Protocol

Secure CRM Scopes: The integration requests granular CRM permissions including crm.objects.contacts.read, crm.objects.contacts.write, crm.schemas.contacts.read, crm.schemas.contacts.write, and crm.objects.owners.read.

Encrypted Storage & Refresh: OAuth access and refresh tokens are securely stored in the PostgreSQL database. Access tokens automatically refresh before expiry without interrupting webhooks or background processes.

On-Demand Schema Provisioning: Authorizing a portal creates no unnecessary properties in HubSpot. The ScaleboX property group and custom fields are created only when you save active field mappings.

Fixed Portal Parameters: Connected Portal Hub ID and Domain values are strictly read-only and derived directly from the authenticated HubSpot OAuth session to prevent accidental misconfiguration.

👥 2. Connecting Outreach Teams (ScaleBox & GetSales)

Workspaces

You can connect multiple ScaleBox and GetSales workspaces (teams) to a single HubSpot portal. Each connected team operates in an isolated context while syncing into the shared HubSpot contact database.

Required Connection Parameters

App API Domain: The base URL of your outreach platform. Default is https://scaleboxapp.com for ScaleBox, or your custom domain for GetSales (e.g. https://app.getsales.io).

App Team ID: The numeric identifier of the workspace (e.g. 657, 663). This ID is visible in your browser address bar when logged into ScaleBox (parameter team_id=...).

API Token (JWT): Generated inside your ScaleBox or GetSales workspace under Settings → Integrations → API Tokens. Must have read access to contacts, flows, pipeline stages, and tags.

Multi-Team Parity: Every connected team has its own dedicated inbound webhook endpoint with matching Team ID tagging in contact properties and integration logs.

⚡ 3. Webhook Setup & Real-Time Sync Guide

Real-Time

Inbound webhooks push newly discovered leads, conversation replies, and status updates directly into HubSpot CRM in real time without polling delays.

Step-by-Step Webhook Configuration

Navigate to Webhooks: Log into your ScaleBox or GetSales dashboard and go to Settings → Webhooks → Add Webhook.

Copy Webhook URL: Copy your team's dedicated webhook URL from the "Connected Outreach Teams" card under the App Connection tab:
https://scalebox-hubspot.vsubbotin.com/webhook/scalebox?portal_id=[HUB_ID]&team_id=[TEAM_ID]

Select Trigger Events: Enable the following three events:

contact.created — Dispatches immediately when a new outreach contact enters the campaign.
contact.updated — Dispatches when status, pipeline stage, tags, or contact properties change.
message.received — Dispatches when a recipient replies on LinkedIn or Email, syncing conversation threads.

Save & Verify: Click Save Webhook. You will immediately see incoming webhook events appearing in the Integration Logs tab.

🎯 4. Owner Synchronization (Agent -> Contact Owner (HubSpot))

Routing

This module matches outreach Agents from all connected ScaleBox & GetSales teams with Contact Owners (HubSpot), ensuring that new leads are automatically assigned to the correct sales representative.

Profile Matching Logic

🔄

Sync Agents from App: Clicking "Sync Agents from App" calls the outreach API to retrieve all active sender profiles across all connected teams.

✓

Automatic Email Matching: If the email address of an Agent matches the email of an active HubSpot User, the owner mapping is assigned automatically.

⚪

Unassigned State (-- None --): If an Agent is mapped to -- None -- or if a lead arrives without an assigned Agent, the contact is synced with the HubSpot Contact Owner left blank.

"Overwrite existing Contact Owner (HubSpot) if Agent changes" Toggle

Lead Scenario	Toggle OFF (Default / Recommended)	Toggle ON
New Contact	Assigns mapped Contact Owner (HubSpot).	Assigns mapped Contact Owner (HubSpot).
Existing Contact without Owner	Fills mapped Contact Owner (HubSpot).	Fills mapped Contact Owner (HubSpot).
Existing Contact with Assigned Owner	Protected: Existing Contact Owner is preserved to protect ongoing deals.	Overwritten: Contact Owner (HubSpot) updates to the new Agent's mapped user.

🗂️ 5. Field Mapping Architecture & Standards

Schema

HubSpot Property Naming Standards

📁

Property Group: All custom outreach properties are created in the contact property group labeled ScaleboX (internal name scalebox).

🏷️

Internal Names & Prefixes: Custom internal names are strictly prefixed with sb_ (e.g. sb_campaign_name, sb_flow_status). Display labels always start with [SB] for instant identification in CRM views and filters.

Field Mapping Controls

🔘

Active Switch: Controls whether this field is processed. Inactive fields are grayed out, disabled, and excluded from HubSpot API requests.

🎯

Destination Types:

Select HubSpot Field: Maps to an existing native property (e.g. firstname, email, phone). The label is synced automatically from HubSpot and locked from manual editing.
Create Custom Field: Provisions a standardized sb_* property in HubSpot CRM. Internal name and label are locked to maintain system integrity.

⚖️

Overwrite Policies:

Always Overwrite: Updated on every incoming webhook event. Suitable for statuses, stages, conversation threads, and URLs.
Write Only if Empty: Only written if the HubSpot field currently has no value. Preserves manual edits made by sales reps. Suitable for first name, phone numbers, and job titles.

📋 6. Complete 38-Field Dictionary & Allowed Values

Data Dictionary

A. Native HubSpot Properties (Select HubSpot Field)

ScaleBox Field	HubSpot Property	Default Policy	Description
`first_name`	`firstname`	Write only if empty	Contact's first name
`last_name`	`lastname`	Write only if empty	Contact's last name
`job_title`	`jobtitle`	Write only if empty	Professional job title
`work_email`	`email`	Write only if empty	Primary business email address
`work_phone_number`	`phone`	Write only if empty	Work phone number
`personal_phone_number`	`mobilephone`	Write only if empty	Mobile / personal phone number
`company_name`	`company`	Always overwrite	Company / organization name
`city`	`city`	Write only if empty	City location
`region`	`state`	Write only if empty	State or province region
`zip`	`zip`	Write only if empty	Postal or ZIP code
`linkedin_url`	`hs_linkedin_url`	Write only if empty	Personal LinkedIn profile URL

B. Dropdown Properties (Single Select — enumeration/select)

Each dropdown property accepts exactly one value from the defined options list.

ScaleBox Field	HubSpot Property	HubSpot Label	Allowed Values (Value -> Label)
`status`	`sb_flow_status`	`[SB] Campaign Status`	`in_progress` (In Progress) `finished` (Finished) `canceled` (Canceled) `ready` (Ready) `restarted` (Restarted) `failed` (Failed) `active_limit` (Active Limit) `ok` (Active / OK) `replied` (Replied) `paused` (Paused)
`linkedin_status`	`sb_li_status`	`[SB] LinkedIn Status`	`ok` (OK / Connected) `connected` (Connected) `invited` (Invited / Pending) `replied` (Replied) `enrichment_failed` (Enrichment Failed) `no_data` (No Data)
`pipeline_stage_name`	`sb_pipeline_stage`	`[SB] Pipeline Stage`	Dynamically synced from ScaleBox pipeline stages (e.g. `New`, `Approaching`, `Engaging`, `Replied`, `In Work`, `Opportunity`, `MQL`, `SQL`).
`employees_count`	`sb_employees_count`	`[SB] Company Employees Count`	`1-10` (1-10 employees) `11-50` (11-50 employees) `51-200` (51-200 employees) `201-500` (201-500 employees) `501-1000` (501-1,000 employees) `1001-5000` (1,001-5,000 employees) `5001-10000` (5,001-10,000 employees) `10001+` (10,001+ employees)
`source`	`sb_source`	`[SB] Source`	`ScaleboX` (ScaleboX), `GetSales` (GetSales)
`primary_language`	`sb_primary_lang`	`[SB] Primary Language`	Two-letter ISO codes: `en`, `ru`, `de`, `fr`, `es`, `it`, `zh`, `ja`, `pt`, `nl`, `pl`, `tr`, `uk`, `ar`, `he`, `hi`, `sv`, `cs`, `el`

C. Multi-Select Properties (Multi-Checkbox — enumeration/checkbox)

Multiple values can be selected simultaneously. In the HubSpot API, values are formatted with a semicolon separator ;.

ScaleBox Field	HubSpot Property	HubSpot Label	Format & Allowed Values
`campaign`	`sb_campaign_name`	`[SB] Campaign / Flow`	Internal Value: Flow UUID (e.g. `f687d1d1-2e52-4d6b-a243-d82bc4a05857`). Display Label: Campaign name with Team ID suffix: `Flow Name [#Team ID]`. Multiple flows are concatenated with `;`.
`tags`	`sb_tags`	`[SB] Tags`	ScaleBox contact tags concatenated with `;` (e.g. `VIP;Outreach2026`).
`supported_languages`	`sb_languages`	`[SB] Supported Languages`	Two-letter ISO language codes concatenated with `;` (e.g. `en;ru;de`).

D. Text & Multi-Line Properties (string/text, string/textarea)

ScaleBox Field	HubSpot Property	HubSpot Label	Type	Description & Format
`scalebox_url`	`sb_lead_url`	`[SB] Profile URL`	text	Direct URL link to the lead's profile in ScaleBox / GetSales
`experience`	`sb_experience`	`[SB] Experience Summary`	textarea	Formatted work history: `[2021 – Present] Company\nPosition: Head of Sales`
`linkedin_thread`	`sb_li_thread`	`[SB] LinkedIn Thread`	textarea	Chronological LinkedIn message history with UTC timestamps and sender labels
`email_thread`	`sb_email_thread`	`[SB] Email Thread`	textarea	Chronological email conversation thread
`hq_location`	`sb_hq_location`	`[SB] HQ Location`	text	Company headquarters location
`list_name`	`sb_list_name`	`[SB] List Name`	text	Name of the lead list in ScaleBox
`headline`	`sb_headline`	`[SB] LinkedIn Headline`	text	LinkedIn profile headline
`timezone`	`sb_timezone`	`[SB] Timezone`	text	Normalized timezone offset (e.g. `+3:00`, `+0:00`, `-5:00`)
`personal_email`	`sb_personal_email`	`[SB] Personal Email`	text	Secondary or personal email
`sender_profile_name`	`sb_sdr_name`	`[SB] SDR Name`	text	Full name of the assigned outreach SDR
`sender_profile_uuid`	`sb_sdr_uuid`	`[SB] SDR Profile UUID`	text	ScaleBox SDR profile UUID
`task_id`	`sb_task_id`	`[SB] Task ID`	text	ScaleBox task identifier
`team_id`	`sb_team_id`	`[SB] Team ID`	text	Numeric Team ID
`user_id`	`sb_user_id`	`[SB] User ID`	text	ScaleBox User ID
`uuid`	`sb_contact_uuid`	`[SB] Contact UUID`	text	ScaleBox Contact UUID (primary deduplication key)
`linkedin_id`	`sb_linkedin_id`	`[SB] LinkedIn ID / URN`	text	LinkedIn profile ID or URN
`twitter`	`sb_twitter`	`[SB] Twitter / X URL`	text	Twitter / X profile URL
`facebook`	`sb_facebook`	`[SB] Facebook URL`	text	Facebook profile URL

🛡️ 7. Dynamic Options Sync & On-The-Fly Safety Net

Fault-Tolerant

HubSpot strictly enforces that any value sent to an enumeration property must exist in the property's predefined options. The integration implements a two-tier architecture to ensure 100% data ingestion reliability:

1. Pre-Caching on Field Mapping Save

When you save field mappings, the connector queries the outreach API for active campaigns (/flows/api/flows), pipeline stages (/leads/api/pipeline-stages), and tags (/leads/api/tags) across all connected teams.

Labels and values are deduplicated to satisfy HubSpot's NON_UNIQUE_OPTION_LABELS validation rule.

If the property already exists in CRM, the new options are merged with existing options via an HTTP PATCH request, ensuring that historical values are never overwritten or deleted.

2. On-The-Fly Safety Net (Real-Time Fallback)

Automatic Option Registration:
If a new campaign is launched or a new pipeline stage is created in ScaleBox while leads are arriving, HubSpot returns an HTTP 400 INVALID_OPTION error.
The connector catches this specific error, registers the missing option in HubSpot via a PATCH API call, and immediately retries the contact sync. The lead is saved without data loss or administrative intervention.

📥 8. Contact Deduplication Hierarchy

Architecture

To prevent duplicate records in HubSpot CRM, every incoming lead is matched against existing contacts using a strict three-tier deduplication sequence:

Match by sb_contact_uuid (Primary Key): Searches for an existing contact with the exact ScaleBox Contact UUID. If found, the contact is updated in place.

Match by email (Work Email): If no contact matches the UUID, the engine searches by work email address via the CRM Search API.

Match by phone / mobilephone: If email is not available or not matched, the engine searches by formatted phone number.

If a match is found in steps 1–3, the existing contact is updated according to the Overwrite Policies configured in the Field Mapping tab. If no match is found, a new contact record is created in HubSpot CRM.

📜 9. Integration Audit Logs & Health Monitoring

Audit

The Integration Logs tab provides an audit log of every incoming webhook event and synchronization operation:

🔗

Direct CRM Record Links: Successfully synchronized contacts display a clickable HubSpot link (#ID ↗) that opens the contact page directly in your HubSpot portal.

🏷️

Status Tags: Logs are labeled with clear status badges: created (new contact), updated (existing contact updated), or error (actionable error message with HTTP status).

📊

Automatic Rotation: The database automatically retains the most recent 5,000 log entries per portal, ensuring optimal system performance.

💬 10. HubSpot Custom Channels & Dynamic SDR Slots

Two-Way Messaging

HubSpot Custom Channels enable native two-way LinkedIn messaging directly from the HubSpot Conversations Inbox and Help Desk. Sales reps and support agents can view incoming messages, read full conversation threads, and compose replies without leaving HubSpot CRM.

Subscription Tiers & Quota Management

Tier	Channel Slots	Data Flow Duration	Description
Trial	3 SDR Slots	30 Days	Evaluation plan with full access to 38 custom properties and 3 channel slots.
Lifetime VIP	10 SDR Slots	99 Years (Unlimited)	Standard full tier for connected accounts. Configured with 10 slots (HubSpot inbox optimal capacity).
Custom / Paid	N Slots	Flexible	Enterprise tier configured with custom quota and duration via subscription calculator.

💡 Quota Formula: Available Slots = Tier Limit − Connected Channel Accounts. The "+ Connect Channel Slot" button is active whenever Available > 0.

Dynamic SDR Slot Switching (History Retention)

Virtual Slot Architecture: Each slot creates a persistent channel account in your HubSpot Conversations Inbox. Instead of recreating channels when team members rotate, the slot simply re-maps to a new SDR profile.

No Thread Breakage: When an administrator selects a different SDR for a slot, existing conversation history and HubSpot Contact associations remain 100% intact.

Instant Outbound Routing: Any subsequent reply typed in the HubSpot Inbox thread immediately routes to the newly assigned SDR's LinkedIn account via ScaleBox.

HubSpot Conversations Inbox Setup

📥

Target Inbox: Choose which HubSpot Conversations Inbox (e.g. Sales Inbox or Default Inbox) receives dialogues. Multiple slots can route to the same inbox.

⚡

Automated Reply Dispatch: Outbound replies from HubSpot are routed via the connector's /webhook/hubspot/messages endpoint and sent to ScaleBox (POST /flows/api/linkedin-messages).

Included with this integration:

HubSpot OAuth Authorization

Connected Outreach Teams / Accounts

⚡ How to Set Up Inbound Webhooks in ScaleBox / GetSales

➕ Connect Outreach Team / Account

Owner Synchronization

Properties & Synchronization Mapping

Standard Contact Properties

System Properties

🏢 Company Synchronization & Association

Company Synchronization is Disabled

Standard Company Properties

System Company Properties

Custom Channels Quota & Plan

Connected Channel Slots

Message Delivery Statuses (4-Stage Pipeline)

Connect New Channel Slot

Switch Assigned SDR

Polling Synchronization & Historical Depth

Run Manual Synchronization

Integration Audit & Sync Logs

Integration Help Center & Documentation

🔌 1. HubSpot OAuth 2.0 Authorization

OAuth 2.0 Standard Protocol

👥 2. Connecting Outreach Teams (ScaleBox & GetSales)

Required Connection Parameters

⚡ 3. Webhook Setup & Real-Time Sync Guide

Step-by-Step Webhook Configuration

🎯 4. Owner Synchronization (Agent -> Contact Owner (HubSpot))

Profile Matching Logic

"Overwrite existing Contact Owner (HubSpot) if Agent changes" Toggle

🗂️ 5. Field Mapping Architecture & Standards

HubSpot Property Naming Standards

Field Mapping Controls

📋 6. Complete 38-Field Dictionary & Allowed Values

A. Native HubSpot Properties (Select HubSpot Field)

B. Dropdown Properties (Single Select — enumeration/select)

C. Multi-Select Properties (Multi-Checkbox — enumeration/checkbox)

D. Text & Multi-Line Properties (string/text, string/textarea)

🛡️ 7. Dynamic Options Sync & On-The-Fly Safety Net

1. Pre-Caching on Field Mapping Save

2. On-The-Fly Safety Net (Real-Time Fallback)

📥 8. Contact Deduplication Hierarchy

📜 9. Integration Audit Logs & Health Monitoring

💬 10. HubSpot Custom Channels & Dynamic SDR Slots

Subscription Tiers & Quota Management

Dynamic SDR Slot Switching (History Retention)

HubSpot Conversations Inbox Setup