HubSpot Grid Integration

The HubSpot Grid integration enables Salesforce users to view, search, inline-edit, create, and delete CRM records from HubSpot (Contacts, Companies, Deals, and Tickets) as well as view live Contact email engagement history directly inside AppColab Grid.

What’s Deployed

One-Time Manual Setup

1. Create a Private App & Obtain a Personal Access Token (PAT)

[!IMPORTANT] Use Personal Access Tokens (pat-...): HubSpot’s standard OAuth bearer tokens (such as CiRuYT...) are temporary and expire after a short window. For persistent grid connectivity, you must use a Personal Access Token (PAT) from a Private App or Service Key (prefixed with pat-na2- or pat-eu1-), which remains valid indefinitely.

Depending on your HubSpot account view, obtain your token using either method:

• In HubSpot Developer / App Accounts (Recommended):

  1. In the left navigation menu, go to Development → Keys → Service Keys.
  2. Click Create service key (or open an existing key like ColabConnect).
  3. Under Scopes, ensure the required CRM permissions are enabled:
     • crm.objects.contacts.read & crm.objects.contacts.write
     • crm.objects.companies.read & crm.objects.companies.write (optional)
     • crm.objects.deals.read & crm.objects.deals.write (optional)
     • sales-email-read (optional, for email engagement history)
  4. Click Copy next to your Service Key (pat-na2-...).

• In Standard HubSpot CRM Portals:

  1. In your HubSpot portal, click the Settings icon ⚙️ in the top navigation bar.
  2. In the left sidebar, navigate to Integrations → Private Apps.
  3. Click Create private app → name it AppColab Grid.
  4. Under the Scopes tab, select crm.objects.contacts.read and crm.objects.contacts.write.
  5. Click Create app (top-right) → confirm and copy the generated token (pat-na2-... or pat-eu1-...).

2. Configure Credentials in Salesforce Setup

2.1 Create the External Credential

1. Go to Setup (gear icon ⚙️ → Setup).
2. In the Quick Find box, enter Named Credentials and select Named Credentials.
3. Click the External Credentials tab → click New:
   • Label: HubSpot
   • Name: HubSpot
   • Authentication Protocol: Custom
   • Click Save.
4. In the Principals section, click New:
   • Parameter Name: ApiKey
   • Sequence: 1
   • Click Save.
5. In the Custom Headers section, click New:
   • Name: Authorization
   • Value: Bearer pat-na2-YOUR_HUBSPOT_TOKEN (paste your Personal Access Token from Step 1, preceded by Bearer )
   • Sequence Number: 1
   • Click Save.

2.2 Create the Named Credential

1. Click the Named Credentials tab (next to External Credentials) → click New:
   • Label: HubSpot
   • Name: HubSpot
   • URL: https://api.hubapi.com
   • External Credential: Select HubSpot
   • Generate Authorization Header: Leave Unchecked (handled by custom Authorization header)
   • Allow Formulas in HTTP Header: Checked
2. Click Save.

3. Assign Permission Set Access

1. In Salesforce Setup, enter Permission Sets in Quick Find.
2. Select Integration Admin (or HubSpot_Integration / your custom admin permission set).
3. Click External Credential Principal Access → click Edit.
4. Add HubSpot - ApiKey to Enabled External Credential Principals.
5. Click Save and verify the permission set is assigned to your Salesforce users.

Creating a HubSpot Grid Definition

1. In Salesforce, open AppColab Grid app → Grid Definitions tab → click New Grid Definition.
2. Fill in:
   • Grid Settings Name: HubSpot_Contacts_Grid
   • Grid Label: HubSpot Contacts
   • Is Active?: Checked
   • Data Provider Class: HubSpotGridDataProvider
   • Data Provider Configuration:

     {
       "objectType": "contacts"
     }
     

     Tip: You can also use "companies", "deals", or "tickets" as the objectType.

3. Click Save & Next → proceed to Preview.
4. All HubSpot contacts load live with First Name, Last Name, Email, Phone, Company, Lifecycle Stage, and Lead Status!

Supported Grid Features

Troubleshooting & Common Gotchas

• Grid preview renders columns but shows “No Records Found” (Silent 401):
  • Cause: HubSpot returns HTTP 401 EXPIRED_AUTHENTICATION (“The OAuth token used to make this call expired…”). The Apex data provider catches callout errors gracefully to prevent UI crashes, which produces an empty record list (0 rows).
  • Fix: In Salesforce Setup > Named Credentials > External Credentials > HubSpot > Custom Headers, verify that the Authorization header is using an active Personal Access Token (Bearer pat-na2-... or Bearer pat-eu1-...), not an expired temporary OAuth token.
• 403 Forbidden: Missing scopes:
  • Cause: The Private App was created without required object scopes.
  • Fix: In your HubSpot portal under Settings → Integrations → Private Apps, edit your app scopes and enable crm.objects.contacts.read (and .write if inline editing).
• 0 records when embedded on a Salesforce Record Page:
  • Cause: When embedded on a Contact Lightning page, the provider matches HubSpot contacts where the email equals the Salesforce Contact’s Email field. If the Salesforce Contact has a blank email or there is no matching record in HubSpot, the grid will be empty.
• Missing External Credential Access:
  • Cause: Users encounter an error indicating principal access is missing.
  • Fix: Assign the permission set containing HubSpot - ApiKey external credential principal access to the user.