Matched USER source: owner-ID uniqueness, failures and refresh behavior

Marketing & Content Hub Lists, Lead Scoring & Workflows
1

Hi everyone,

In a Deal workflow, we saved and ran an input-only diagnostic using a matching-record data source: USER.hubspot_owner_id = the enrolled Deal’s hubspot_owner_id. With the “Most recently updated” refiner, it returned a USER with the expected owner ID and hs_deactivated=“false”. The diagnostic made no business-record updates.

Before adding a later update action, we’re looking for documented behavior on two points:

  1. Is USER.hubspot_owner_id guaranteed unique within an account, including after user deactivation or removal? If not, is there a supported way to stop rather than select a record when multiple matches exist?

  2. How can we distinguish no match from a source read failure, and what refresh or re-evaluation guarantees, if any, apply when the Deal owner or USER changes before a later update action?

Official documentation or a supported configuration pattern would be appreciated.

Thanks!

3

Hi @LeonKingsley, I hope that you are well!

Thanks for asking the HubSpot Community!

I can see that the current documentation supports matching records and filtering down to one, but doesn’t explicitly guarantee that USER.hubspot_owner_id is unique or that a workflow will stop if multiple matches are found.

I’d recommend treating Most recently updated as a way to select a record rather than confirm uniqueness. While User ID is documented as unique, its behavior after user deactivation or removal isn’t clearly specified. I’d suggest reaching out to our Support Team if you need more details about this as they can investigate further.

Here is the article for reference: Add data variables to workflow actions

I’d love to check with our Top Experts: Hi @Anton, @evaldas and @zach_threadint do you have any insights on this, please?

Thanks so much and have a lovely weekend!

Bérangère

5

Thank you, Bérangère, for clarifying the selection behavior and sharing the documentation. We will treat “Most recently updated” as selection, not proof of uniqueness, and keep empty or uncertain results on hold.

We are using a regular Deal workflow’s added User data source, with User Owner matching the enrolled Deal owner and “Most recently updated” selecting one. We map User record ID, Owner and Deactivated into custom code. We have not found source-result metadata in the editor we inspected, but have not verified every mapping option.

Could you point us to the supported approach for these remaining details?

  1. Source outcomes: Is there a source-specific status/error and complete match count before selection, accessible through a token, log or API? We would keep both an empty result and a failed lookup on hold, but need to distinguish them diagnostically. If resolution prevents the action from running, where are that outcome and any retries recorded? How can we tell whether a count is complete rather than capped?

  2. Edge cases: With an empty Deal owner, does matching return no result, match empty User Owner values, or fail? Are deactivated or removed Users still selectable, and which identity/status fields remain available? Does this matching mode support an additional active-user filter? If multiple matches have the same last-updated time, is the selection rule defined? We would also keep active status separate from seat/role/permission eligibility.

  3. Timing and alternative: When are these values resolved and refreshed across delays or retries, and are the selected identity/status from one read? Is any source-read timestamp or cache-age bound available? If this source cannot provide the needed information, which supported action or API is the best alternative? In particular, does Agent Hub Find one/Find many support Users, or is an Owners/Users API approach more appropriate? The relevant identifier mapping, paging/limits, inactive-user behavior and product/seat/public-scope requirements would help us evaluate that recommendation.

Documentation or a clear statement of the supported limits would be very helpful. This is a capability review; we will review the recommendation before running new tests or changing the account.

Thanks,
Leon

6

Hi @LeonKingsley and thanks for the follow up!

Here’s what we can confirm from the current documentation, along with the approach we’d recommend.

1. Data-source results and visibility

HubSpot’s documentation explains how to configure matching conditions and use refiners such as Most recently updated, Most recently created, or First created to select a single record.

However, it doesn’t currently document a way to view match counts, distinguish an empty result from a failed lookup, or confirm whether all matching records were returned.

For now, your approach of pausing the process in either scenario makes sense. You can also review the workflow’s action history to investigate individual executions, although we’d recommend validating how lookup failures appear before relying on those logs.

2. Edge cases and timing

A few behaviors aren’t explicitly covered in the documentation, including how empty values are handled, whether inactive users remain selectable, how ties are resolved, and when data-source values are refreshed.

3. Recommended approach: Owners API

For your use case, I’d recommend using the Deal’s hubspot_owner_id with the HubSpot Owners API.

This allows you to look up a specific owner directly, avoiding the uncertainty of multiple matching records.

The Owners API also supports retrieving archived owners, which can be helpful when working with deactivated users. Just keep in mind that owner information and user status or permissions are separate considerations.

If you need additional user-level information, the Users/SCIM API is the documented option, subject to the appropriate permissions.

4. Next steps

The questions you’ve raised around match-count visibility, lookup failures, refresh timing, and Users object support are valuable feedback for improving the documentation and functionality.

I’ll flag these gaps to the relevant team for review and I’d suggest submitting the HubSpot Developer Feedback Form .

Thanks again for bringing such specific examples to the Community!

Bérangère

This post was created with the assistance of AI tools

7

Hi Bérangère, thank you for suggesting a direct lookup by Owner ID. We’re reviewing that route and keeping owner information separate from user status. Once we’ve identified the active or archived owner, is there a recommended read-only endpoint or set of user fields for checking whether that user is currently eligible to be assigned as a Deal owner? I read that an owner’s updatedAt does not track user permission changes. If assignment eligibility isn’t exposed directly, knowing that limitation would also help us choose the right approach. Thank you!

8

Hi @LeonKingsley and thanks for following up!

Let’s consult our Top Experts: Hi @trevordjones, @EugeneAtKiwi and @MichaelMa do you know about a read-only API endpoint to check whether a user is eligible to be assigned as a Deal owner or do you have a workaround to share, please?

Have a great day and thanks so much!
Bérangère

- For information, I’ll be out of the office on Monday 19th of October -

9

Hi @LeonKingsley and all,

To get back to you on this, currently, there isn’t a dedicated read-only endpoint that checks deal-owner eligibility. A workaround is to use the owners API.

  • Call GET /crm/v3/owners?email={email}.
  • If the user comes back with archived: false and an owner id, they exist as an owner. You can use that id as hubspot_owner_id when assigning ownership.
  • Archived (deactivated) users only appear if you add archived=true. They have a null userId.
  • Use the owner id, not userId. The userId causes an error if you use it to assign ownership.

Let us know how it goes!

Thanks,
Bérangère

This post was created with the assistance of AI tools