HubSpot custom objects allow you to track unique business data beyond the standard Contacts, Companies, and Deals. By defining new objects with their own properties and associations, they fundamentally transform HubSpot CRM into a highly tailored system, perfectly aligned with your business needs. Think of them as bespoke entities designed specifically for your organization’s unique requirements, whether that's Products, Assets, Subscriptions, Events, or anything else your business tracks. Once defined, you can perform actions to query or manipulate this data as required.
Now, speaking of actions, in any integration scenario, the ability to perform an Upsert is absolutely crucial. Upsert is a compound operation that intelligently handles both inserting a new record and updating an existing one in a single operation. It relies on a unique identifier (like an ID or a custom unique property) to determine the final write operation. Without this functionality, integrations become much more complex and time-consuming, requiring a manual process to first check if a record exists and then conditionally perform an update or an insert. This complexity applies equally to standard and custom objects.
Fortunately, the HubSpot API provides support for Upsert service calls that allow creating or updating custom object records with ease. By using KingswaySoft's HubSpot components, you can easily implement such Upsert operations in your ETL integration processes.
In this blog post, we will be demonstrating how to configure and achieve this powerful functionality. You can find the necessary components in the SSIS Integration Toolkit for HubSpot.
Let's dive right in!
Configure a Unique ID for the Custom Object
To perform an Upsert action (a batch upsert call), the API endpoint mandates including the idProperty parameter in the request body, and this is defined by the API as a property with a unique value for the object. The "id" corresponds to the actual value for the field, while the "properties" node contains the key-value pairs representing the object properties (i.e., the rest of the data to be written to the record).
As a first step, you would need to define a field as a Unique field in HubSpot customization. For this, you can navigate to the settings page for the custom object and click on "Manage <custom object name> properties".
As of now, HubSpot doesn't provide a way to set an existing field as a Unique property, and you can only set this property when a field is newly created. Click on "Create property" to launch the process.
Next, provide the details required to create the unique ID field.
Within the "Create Property" page, select "Rules", and under "Basic Rules", enable the checkbox for "Require unique values for this property".
Save and create the property. Once done, you are now ready to move over to your SSIS development environment to create a data flow that writes your custom object records to HubSpot via an SSIS HubSpot destination component.
Setting up the SSIS data flow
Within your data flow, when you open the HubSpot Destination component and choose your Custom object, you will get to pick the Upsert action. The "Id Property" field that shows up in the general page lets you pick the pre-defined unique ID fields that you had created in the previous section within HubSpot. Once a field is chosen, the component will prompt you to map the chosen field.
The mappings for the unique field and other fields can be done in the columns page. If you created the unique field after the component was previously configured, then the "Refresh Component" button can get you the latest metadata.
Save and close the component. At runtime, the request will be sent from the component to the endpoint as shown below, in the required full format for batch Upsert.
In the response, it would indicate whether the action was a Create/Insert or an Update.
And this is also available as a part of the default output in the HubSpot Destination component, which returns a boolean value.
Conclusion
In short, leveraging HubSpot custom objects allows you to tailor the CRM to your precise business needs. The crucial Upsert action, available through the HubSpot API and easily implemented with KingswaySoft's SSIS Integration Toolkit, simplifies your integration workflows by intelligently handling both inserts and updates. This functionality is essential for maintaining accurate, efficient data synchronization. By adopting this approach, you ensure your HubSpot data remains a highly tailored and reliable asset.
We hope this helps!