HubSpot lookup against company profiles

This feature expands HubSpot integration to include Company objects as valid lookup targets alongside Contact objects. It enables contact center teams to identify callers or chatters by their associated company profile if a specific contact record is not available, improving identification rates.

This guide covers how to enable the Company lookup, configure primary and secondary search priorities, and define specific phone number fields for matching.

Before you begin

Before you begin, ensure the following requirements are met:

  • Permissions: You must have Administrator permissions and the edit_developer_settings permission to access these configurations.
  • Integration: The HubSpot CRM integration must be active.

Configure the primary lookup object

This section describes how to define the first object that Contact Center AI Platform (CCAI Platform) will search when a session begins.

  1. Go to Settings > Developer Settings > CRM > HubSpot.
  2. Navigate to the Account Lookup section, located before the Phone Number Format section.
  3. Expand the Primary Lookup Object section.
  4. In the Object Type dropdown, select either Contact (default) or Company.
  5. In the Phone number lookup fields dropdown, select the fields CCAI Platform should use to match the end-user's phone number.
  6. Use the Phone number primary field dropdown to choose between the consumer's Phone Number (Default setting) or Mobile Phone Number being stored when creating a new CRM account.
  7. Click Save.

The CCAI Platform backend will first perform lookups against the object type selected as the primary lookup object.

Configure the secondary lookup object

The secondary lookup serves as a fallback if no match is found in the primary object.

  1. Go to Settings > Developer Settings > CRM > HubSpot > Account Lookup.
  2. Locate the Secondary Lookup Object section and check the checkbox to enable it.
  3. The Object Type dropdown will be automatically set to the type not used for the primary lookup (e.g., if Primary is Contact, Secondary is automatically Company).
  4. Select the desired Phone number lookup fields for this secondary object.
  5. Configure Custom User ID fields if you need to perform lookups via SDK custom fields or SIP headers for this object.
  6. Click Save.

If the primary lookup returns no results, CCAI Platform will automatically execute a second search against the secondary object.

Understand lookup cascade logic

CCAI Platform follows a specific order of operations to ensure efficient data retrieval from HubSpot.

Expected behavior:

  • Direct ID Match: If a contact_id is provided, CCAI Platform performs a direct GET call first for the fastest result.
  • Combined Search: All other identifiers (phone, email, SDK identifier, or SIP identifier) are searched simultaneously using OR logic within HubSpot's FilterGroups.
  • Primary First: The search is executed against the Primary Lookup Object.
  • Secondary Fallback: If the primary search is empty and a secondary object is configured, CCAI Platform repeats the search against the secondary object type.
  • First Match Wins: CCAI Platform returns the first successful match found in this cascade.