HubSpot Deals API: Retrieve Description & Owner Properties

Ever found yourself scratching your head, wondering why some seemingly 'basic' data isn't showing up when you pull information from HubSpot's API? You're definitely not alone. It's a common scenario, and one that recently sparked a great discussion in the HubSpot Community. We're talking about those elusive deal properties like 'description' and 'owner' – vital pieces of information that can make or break your reporting, automation, or even your custom built online site builder integrations.

Developer writing code to retrieve HubSpot Deal properties using API query parameters.

The Case of the Missing Deal Properties

The original poster, a fellow HubSpot user, was trying to retrieve all their Deals through the API. Their goal was straightforward: get deal amounts, dates, statuses, and crucially, the description and owner. But those last two? Nowhere to be found. It felt fundamental, yet the data just wasn't there.

The Initial Expert Advice: Explicitly Ask for What You Want

A community manager quickly jumped in, clarifying a key point: by default, the HubSpot Deals API doesn't return all properties. Many, including 'owner' and 'description', need to be explicitly requested. Think of it like ordering a custom coffee – you have to specify every ingredient. Another seasoned community member echoed this, advising to append a query parameter like ?properties=description,hubspot_owner_id to the API URL. They also wisely pointed out that internal property names can sometimes differ from what you see in the HubSpot UI, so always double-check.

For instance, while you might see 'Deal Owner' in the UI, the internal API name is typically hubspot_owner_id. Similarly, 'Description' is often just description. Consulting the HubSpot API documentation or using the properties schema API endpoint is always the best way to confirm these internal names.

Example API Call for Specific Deal Properties

To retrieve specific properties for a deal, your API call would look something like this:

GET https://api.hubapi.com/crm/v3/objects/deals/{dealId}?properties=amount,dealstage,description,hubspot_owner_id

When fetching all deals, you'd apply the same principle:

GET https://api.hubapi.com/crm/v3/objects/deals?properties=amount,dealstage,description,hubspot_owner_id

The Plot Thickens: Why 'Description' Still Wasn't Showing Up

Our original poster, however, wasn't getting anywhere. They confirmed they were already specifying the properties, and still, 'description' wasn't coming through. Other properties like 'amount' worked fine, but 'description' remained stubbornly absent. This is where a crucial nuance comes into play: how the API handles properties with no set value.

Initially, it might appear that records without a description simply don't return the 'description' property at all. However, a community member clarified that the API does include the requested 'description' element in the JSON structure, but its value is returned as null if no description is set. The original poster later confirmed this, realizing that their test records simply lacked descriptions. This highlights the importance of robust error handling and null checks in your integration code.

Here's an example of what you might expect when a description is present versus when it's null:

{
  "id": "56383560305",
  "properties": {
    "createdate": "2026-02-16T16:37:39.412Z",
    "description": "A deal description", // Description is present
    "hs_lastmodifieddate": "2026-04-10T14:12:13.144Z",
    "hs_object_id": "56383560305"
  },
  "createdAt": "2026-02-16T16:37:39.412Z",
  "updatedAt": "2026-04-10T14:12:13.144Z",
  "archived": false
}

// ... and for a deal without a description:

{
  "id": "56383560306",
  "properties": {
    "createdate": "2026-02-16T16:37:39.412Z",
    "description": null, // Description is null
    "hs_lastmodifieddate": "2026-04-10T14:12:13.144Z",
    "hs_object_id": "56383560306"
  },
  "createdAt": "2026-02-16T16:37:39.412Z",
  "updatedAt": "2026-04-10T14:12:13.144Z",
  "archived": false
}

The Owner ID Dilemma: Getting the Name, Not Just the Number

Another common pain point highlighted in the thread was the 'owner' property. The API returns the hubspot_owner_id, which is a numerical ID, but not the owner's actual name. For many applications, especially reporting or displaying information on a custom storefront or a whatsapp store builder, the name is far more useful than an ID.

To get the owner's name, you have a couple of options:

Additional API Call: After retrieving the hubspot_owner_id from a deal, you can make a separate API call to the HubSpot Owners API (/crm/v3/owners) to fetch the owner's details, including their first name, last name, and email. You'd typically cache this information to avoid making excessive API calls for every deal.
HubSpot Workflows: As suggested by a community member, you can leverage HubSpot workflows to create a custom property on the Deal object (e.g., 'Deal Owner Name') and populate it with the owner's name using workflow actions. This denormalizes the data but makes it directly accessible when querying the Deal object, saving you a secondary API call.

Why This Matters for E-commerce and RevOps with ESHOPMAN

For ESHOPMAN users, accurate and complete deal data is the lifeblood of efficient e-commerce operations, sales management, and RevOps. Imagine:

Personalized Storefront Experiences: Using deal descriptions to understand specific customer needs or custom order details, allowing your ESHOPMAN storefront to present tailored options or follow-up communications.
Enhanced Reporting: Accurately attributing sales to specific owners and understanding the context (via descriptions) of high-value deals helps in performance analysis and strategic planning.
Automated Workflows: Triggering specific actions in your e-commerce backend or marketing automation based on deal descriptions or owner assignments. For example, assigning a deal with a specific description to a product specialist, or sending a custom quote generated by your web store builder free integration.
Seamless CRM-to-Storefront Sync: Ensuring that your HubSpot CRM data flows effortlessly into your ESHOPMAN storefront, providing a unified view of customer interactions and sales progress.

Best Practices for HubSpot API Integrations

Always Consult Documentation: The HubSpot Deals API documentation is your definitive guide. Property names, available endpoints, and rate limits are all detailed there.
Verify Internal Property Names: Don't assume. Use the Properties API to fetch schema for objects (e.g., Deals) and confirm the exact internal names of the properties you need.
Handle Null Values Gracefully: Always anticipate that properties might return null. Implement robust error handling and conditional logic in your code to prevent unexpected behavior.
Optimize API Calls: For properties like owner name, consider caching owner data or using workflows to enrich deal properties directly, reducing the number of API calls and improving performance.
Monitor Rate Limits: Be mindful of HubSpot's API rate limits. Batching requests and implementing exponential backoff can help manage this.

Conclusion

Navigating the HubSpot API, especially when dealing with specific properties like 'description' and 'owner', can sometimes feel like a treasure hunt. However, by understanding the nuances of explicit property requests, handling null values, and managing associated object data, you can unlock the full potential of your HubSpot CRM data. For ESHOPMAN users, this means a more powerful, integrated, and insightful e-commerce experience, driving better sales outcomes and streamlined RevOps.