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 Administratorpermissions 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 Lookupsection, located before the Phone Number Formatsection.
3. Expand the Primary Lookup Objectsection.
4. In the Object Typedropdown, select either Contact(default) or Company.
5. In the Phone number lookup fieldsdropdown, select the fields CCAI Platform should use to match the end-user's phone number.
6. Use the Phone number primary fielddropdown to choose between the consumer's Phone Number(Default setting) or Mobile Phone Numberbeing 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 Objectsection and check the checkbox to enable it.
3. The Object Typedropdown 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 fieldsfor this secondary object.
5. Configure Custom User ID fieldsif 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.