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 Alternative Property if you rely on unique IDs or email addresses, or Optional Alternative Property for the most robust, multi-field matching.

1. Default Property (Social Profile)

• Uses the LinkedIn Profile URL (profile_url from 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

• Uses the os_objectlookup_id variable. To enable this, add os_objectlookup_id to 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

• 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_id is 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

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

Next step

• Run a webhook test payload

Related guides

• Handling Linkedin Urls For Matching