Using custom lead/contact object lookup ID

When to use this guide: Use this guide when you are onboarding OutboundSync or validating initial setup.

This feature is only supported by Instantly, EmailBison, and HeyReach since they pass custom fields/properties with every event they send to OutboundSync. This feature is not supported by Smartlead at this time.

When OutboundSync receives activities from your Sales Engagement Platform, we need to do an API call into your CRM to see if that lead/contact exist or not. This can be done by email address, the record ID, another default field/property, or a custom field/property.

Lookup by email address

When syncing email data, OutboundSync will default to using the email address. Ensure this field/property is included in your Sales Engagement Platform (including social platforms like HeyReach), and the sync will work automatically.

Lookup by anything else

If you want to do a lookup by record ID, another default field/property, or a custom field/property, then you’ll need to include a custom field/property in your Sales Engagement Platform.

Using os_objectlookup_id

A custom field/property named os_objectlookup_id needs to be included when you import your leads in your Sales Engagement Platform. This is particularly easy if you are using a tool like Clay to build your lead lists.

When social profile URL alone is not unique in your CRM — for example, inactive and active contacts that share the same URL after a job change — os_objectlookup_id is the primary fix. It lets OutboundSync match the exact HubSpot record you enrolled instead of relying on URL matching and a create-date tie-breaker.

Creating your field/property

If you are using a default field/property in your CRM, then you can skip to the next step. If not, then carefully consider how you create the new field/property that you will use as your reference.

HubSpot and Salesforce offer the ability to enforce uniqueness for custom fields/properties to ensure you don’t create duplicates. Note that HubSpot limits how many properties this can be applied to.

Selecting your field/property

In the OutboundSync webhook receiver settings, select the field/property that you want OutboundSync to search for before logging activities to your CRM.

HubSpot record ID for HeyReach (recommended for duplicate-contact models)

Use this setup when HubSpot may contain multiple contacts with the same social profile URL:

In HubSpot, open the active contact you are enrolling in HeyReach.
Copy its Record ID (contact object).
In the HeyReach lead list, add a custom variable named exactly os_objectlookup_id with that record ID on each row.
In the OutboundSync webhook receiver, select Optional Alternative Property and map Object Lookup Selection to HubSpot Record ID.
Run a test webhook payload to confirm activity lands on the intended contact.

If an agency or internal team builds HeyReach lists, they must include the os_objectlookup_id column with the target HubSpot record ID for each lead.

What happens without a unique lookup key

When OutboundSync falls back to social profile URL matching and HubSpot returns multiple contacts, it selects the record with the most recent create date. Activity may land on a newer contact even when your campaign targeted a different one.

See Lookup method options for HeyReach sync for tie-breaker details and the job-change active/inactive contact pattern.

Test it with OutboundSync

Not sure if you set everything up correctly? Test it!

You can test your payloads using the Test Sync for your webhook receiver, also known as the testing modal, in OutboundSync.

For a detailed explanation, read the Sending test webhook payloads article in the help center.

You can also send test data through tools like Postman, or using curl in your terminal.

Next step

Run a webhook test payload