Lookup method options for HeyReach sync
When to use this guide: Use this guide when configuring or validating engagement platform integration behavior.
When syncing HeyReach activity into your CRM via OutboundSync, the Lookup Method determines how OutboundSync identifies and matches the correct contact record to write activity to.
Unlike email sequencing tools which always provide an email address, HeyReach payloads always include a LinkedIn Profile URL. For this reason, OutboundSync defaults to using the LinkedIn Profile URL as the unique identifier when finding contacts in the CRM. However, this can be configured to use other variables.
Currently, there are three Object Lookup Method options:
Recommendation: Most users should start with Default Property (Social Profile). Use Optional Alternative Property when you want a unique identifier first (for example, CRM record ID via os_objectlookup_id) with social profile URL and email as fallbacks. Use Alternative Property when you match on a single unique identifier and do not need URL or email fallbacks.
1. Default Property (Social Profile)
Section titled “1. Default Property (Social Profile)”- Uses the LinkedIn Profile URL (
profile_urlfrom HeyReach). - In the webhook setup, the Profile URL dropdown lets you choose which CRM field to map this to — either the standard LinkedIn URL field or a custom property.
- Upsert behavior: Updates the contact if a match is found, or creates a new contact if no match exists.
2. Alternative Property
Section titled “2. Alternative Property”- Uses the
os_objectlookup_idvariable. To enable this, addos_objectlookup_idto your lead list in HeyReach — it will then be included in the webhook payloads. - In OutboundSync, the Object Lookup Selection field (in the webhook setup) lets you map this identifier to the correct property/field in your CRM.
- This method gives your team flexibility to match contacts based on any unique identifier you maintain (e.g., CRM record ID, email address, or other custom keys).
- Update Only behavior: If a match is found, OutboundSync updates the existing record. If no match is found, a new contact will not be created.
3. Optional Alternative Property
Section titled “3. Optional Alternative Property”- Uses a triage lookup sequence: OutboundSync first checks the Object Lookup Selection field (
os_objectlookup_id), then the Profile URL (profile_url), and finally the Email field you’ve mapped in the webhook setup. - This layered approach provides the most precise matching, since multiple fields are considered and CRM enrichment doesn’t need to be perfect.
- If
os_objectlookup_idis not provided in the payload, it is skipped in the lookup triage. - Upsert behavior: Updates an existing record when a match is found; creates a new contact if none of the fields match.
Lookup Method Comparison
Section titled “Lookup Method Comparison”| Lookup Method | Identifier(s) Used | Webhook Fields to Configure | Behavior | Best For |
|---|---|---|---|---|
| Default Property (Social Profile) | LinkedIn Profile URL (profile_url) | Profile URL → map to standard LinkedIn field or custom property | Upsert: update if matched; create if not | General use; reliable since HeyReach always includes LinkedIn URL |
| Alternative Property | os_objectlookup_id (added to HeyReach lead list) | Object Lookup Selection → map to CRM field holding your chosen identifier | Update Only: update if matched; no new contact created | Teams that want to match on a different unique identifier (e.g., CRM record ID, email, or other custom key) |
| Optional Alternative Property (Triage) | Lookup order: 1) os_objectlookup_id → 2) LinkedIn URL → 3) Email | Object Lookup Selection, Profile URL, Email | Upsert with sequence: update if matched at any step; create if none match | Teams needing the most precise matching; allows multiple identifiers so enrichment doesn’t need to be perfect |
When a lookup matches more than one HubSpot contact
Section titled “When a lookup matches more than one HubSpot contact”This applies when Default Property or Optional Alternative Property falls through to social profile URL (or email) matching and HubSpot returns more than one contact for that value.
OutboundSync selects one record and writes activity to it. The tie-breaker is the contact with the most recent create date (createdate, descending). Older records are not updated.
What this means in practice: activity may land on a different contact than you intended when multiple records share the same social profile URL or email.
To avoid relying on the tie-breaker, pass a unique identifier in every HeyReach payload — see Using custom lead/contact object lookup ID.
