HubSpot API: Log User Names from Property History for Accountability

Hey there, ESHOPMAN readers! As your friendly HubSpot and e-commerce experts, we often talk about automating customer journeys and optimizing sales funnels. But what about the internal processes? Knowing who did what inside your HubSpot portal is just as critical, especially for accountability, audit trails, and seamless internal communications. For businesses looking to build a free webstore or optimize their existing e-commerce setup within HubSpot, understanding these internal data flows is paramount.

Recently, a fascinating discussion popped up in the HubSpot Community that perfectly illustrates this challenge. It’s a common scenario that many RevOps teams, marketers, and e-commerce managers face: needing to log the specific HubSpot user who performed an action, but hitting a snag with the API.

Diagram showing HubSpot workflow with custom code action making an API call to Owners API to update a contact property.

The HubSpot Community Problem: "Who Enabled Jira Access?"

The original poster in the community thread laid out their goal very clearly: when a specific contact property (jira_secured_performance_backlog_access) is set to "Yes", they wanted to automatically populate another field (jira_access_aangezet_door) with the First and Last Name of the user who made that change. This is brilliant for internal emails, audit logs, and ensuring everyone knows who to follow up with.

However, they ran into a wall. While their script successfully identified the sourceId (which is a HubSpot User ID) from the contact's property history, their subsequent API call to retrieve the user's name returned zero results. Their log snippet was quite telling:

INFO USER ID: 69604009 | INFO TOTAL USERS: 0 | INFO MATCH FOUND: false

They had enabled the right permissions (crm.objects.contacts.write, crm.objects.owners.read, settings.users.read, crm.objects.contacts.read) and tried different field types, but the user lookup just wasn't happening.

Cracking the Code: Owners vs. Users (and the Right API)

This is where things can get a little nuanced in HubSpot's API landscape. The core of the problem often lies in understanding the distinction between a "User" and an "Owner" in HubSpot, and which API endpoint to leverage for specific data.

Understanding HubSpot's User & Owner Concepts

HubSpot Users: These are individuals with login access to your HubSpot account. They can be administrators, marketers, sales reps, service agents, etc. The Account | Users API is generally used for managing these user accounts at an organizational level, often for system users or specific account settings.
HubSpot Owners: These are specific HubSpot Users who are designated to "own" CRM records like contacts, companies, deals, and tickets. They are typically the sales reps, service agents, or other team members directly responsible for managing relationships with those records. The CRM API | Owners is designed to retrieve information about these CRM owners.

When you look at the property history of a contact, the sourceId that indicates who made a change most commonly refers to the Owner ID of the user who performed that action within the CRM. While this ID belongs to a HubSpot User, the direct lookup for their first and last name is best done via the Owners API, not the general Users API, for CRM-related actions.

The Solution: Leveraging the CRM Owners API

The community member's log snippet, showing a valid USER ID but zero results from a user lookup, strongly suggests that the API call was directed at the wrong endpoint or was not correctly structured for retrieving owner details. The correct approach involves using the CRM Owners API.

Step-by-Step Implementation (Conceptual Workflow with Custom Code Action):

Trigger the Workflow: Set up a HubSpot workflow that triggers when the specific contact property (e.g., jira_secured_performance_backlog_access) is updated to "Yes".
Retrieve the sourceId: Within the workflow, use a Custom Code Action. This action will need to access the contact's property history for the relevant field. HubSpot's Custom Code actions can access contact properties, including historical values. The key is to find the most recent change and extract the sourceId associated with it.
Call the CRM Owners API: Once you have the sourceId (which is the ownerId in this context), your Custom Code Action will make an API call to the HubSpot CRM Owners API. The specific endpoint you'd target is /crm/v3/owners/{ownerId}. This allows you to fetch details for a single owner directly by their ID.
Example API Call (Conceptual):
```
GET https://api.hubapi.com/crm/v3/owners/{sourceId}
```
Extract User Names: The response from the Owners API will contain detailed information about the owner, including their firstName and lastName. Your custom code will parse this response to extract these values.
Update the Target Field: Finally, your Custom Code Action will update the designated contact property (e.g., jira_access_aangezet_door) with the retrieved "First Name Last Name" string. If the target field is a "HubSpot User" field type, you might need to pass the ownerId directly, or if it's a simple text field, the concatenated name string.

Essential Permissions

For this process to work, your API key or private app must have the correct permissions. The original poster correctly identified crm.objects.owners.read as crucial, and indeed it is. Without this permission, the Owners API will return unauthorized errors or empty results.

Best Practices and Advanced Considerations

Error Handling: Always build robust error handling into your custom code. What if the sourceId doesn't correspond to an active owner? What if the API call fails? Implement try-catch blocks and logging to diagnose issues.
Deleted Users/Owners: If a user is deleted from HubSpot, their ownerId might no longer resolve to a valid owner. Consider logging the ID along with a note if the name cannot be retrieved, ensuring your audit trail remains intact.
Alternative Scenarios: In rare cases, a sourceId might refer to an internal system user or an API key that isn't directly mapped to a CRM owner. If the Owners API consistently fails for certain sourceId values, you might need to investigate if the general Users API (/crm/v3/users) is more appropriate, though this is less common for direct CRM record changes.
Audit Trails for E-commerce: For ESHOPMAN users, this level of internal tracking is invaluable. Imagine tracking who last updated a product's price, who approved a discount code, or who changed an order status. This ensures accountability and smooth operations, especially in a dynamic e-commerce environment. This level of integration and data transparency is crucial, especially for complex setups, perhaps even for those migrating from or integrating with systems like CRM Magento.
Custom Code Action Limitations: Be mindful of the execution limits and timeouts for HubSpot Custom Code actions. Optimize your code to be efficient.

Conclusion

Logging the specific HubSpot user who performs an action is not just a nice-to-have; it's a fundamental requirement for robust internal processes, accountability, and effective communication. The key to unlocking this data from HubSpot's API, especially when dealing with CRM record changes, lies in correctly distinguishing between HubSpot Users and Owners and leveraging the powerful CRM Owners API.

By implementing a well-designed Custom Code Action in your HubSpot workflows, you can transform a mere ID into a meaningful name, enhancing your audit trails and empowering your team with the context they need to operate seamlessly. At ESHOPMAN, we believe that a well-integrated and transparent internal system is just as vital as a smooth customer experience for any successful e-commerce business built on HubSpot.