Introduction
HubSpot’s expansive platform is packed with essential tools to help marketing, sales, and service teams execute strategy with ease. In an ideal world, these teams can live exclusively within the HubSpot platform without having to hop across a slew of other disparate softwares to get their jobs done.
Of course, there are other tools that other teams within a business might use. Key data from these tools may be beneficial for the marketing, sales, or service teams for visibility, segmentation, reporting, or automation purposes. HubSpot’s app marketplace has tons of native integration installs available to hook third-party softwares into HubSpot (like QuickBooks, PandaDoc, Salesforce, just to name a few). However, there are instances where these native integrations don’t quite fit business logic needs, or there simply isn’t a native connection with a desired software.
Custom integrations, typically code-driven and oftentimes developed and maintained by a third-party vendor (*cough* OBO), can fill these gaps. Code can be written to match business logic cases to sync data between disparate softwares, typically leveraging APIs.
Let’s take a look at a relatively new feature HubSpot developed to help improve the efficiency of these custom-coded integrations, allowing teams to stay within the bounds of Hubspot and still have access to key data from other systems.
External ID (idProperty) Properties
This one is a game changer, especially in relation to custom integrations with other softwares or platforms. But in order to fully understand how it works, you’ll need to know a couple of concepts.
External IDs are object-level fields that act as a unique identifier from an outside system. In other words, it’s a field that holds IDs from a system that isn’t HubSpot.
Let’s say you’re integrating HubSpot with an ERP and you need to sync your ERP accounts with HubSpot companies. You’ll need to write code that pulls updates from the Accounts database of the ERP and pushes those updates into HubSpot, creating new records or updating existing ones.
That sounds straightforward, and it mostly is! But how does your code know when to actually create versus update? Typically, you’ll want to look up on some sort of key field that’s consistent across both systems. In this case, we’ll want to use the ERP account ID. So we’ll create a custom field on the Company object in HubSpot (let’s call it ERP Account ID) and our code will look up on that field. If a company is found with the same ERP Account ID as an account record from the ERP, we’ll know to update that record.
Before HubSpot introduced the idProperty tag, the code logic to get this done wasn’t entirely straightforward. You’d either have to use the Search API to find a company by a given ERP Account ID, or have some sort of semi-grandiose pull logic to get all company records until you find the one with that ERP Account ID. Both of these methods can be relatively slow and neither guarantees that there aren’t duplicate companies (multiple companies with the same ERP Account ID field value).
The idProperty designation on a field allows you to treat that field as an ID field when making API calls (saving API calls and time) and ensures that the values for that field are unique (hence the external ID tag).
In other words, the idProperty designation allows for faster, smoother custom integrations with external systems.
How to Code External idProperties in HubSpot
Creating an external ID field is incredibly straightforward; in fact, there’s really only one additional designation that needs to be made in the request body when creating an object’s property via the API: “hasUniqueValue”: true
For a more comprehensive example, following our ERP integration example, here’s how you might make a cURL request to create an ERP Account ID field on the Company object in HubSpot:
curl --location --request POST 'https://api.hubapi.com/crm/v3/properties/companies?hapikey=YOURHUBSPOTAPIKEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"label": "ERP Account ID",
"name": "erp_account_id",
"type": "string",
"fieldType": "text",
"groupName": "companyinformation",
"hidden": false,
"hasUniqueValue": true,
"formField": false
}'
Here, we’ve named our field ERP Account ID, set the field as a string/text type (we’re assuming our ERP IDs are alphanumeric) and then set the hasUniqueValue to true, which ensures more than one record cannot have the same property value and can also be used as the ID in your GET, PATCH, and DELETE requests instead of the HubSpot Company ID.
Here’s how your GET request URL would look if you wanted to use the field we just created as the set ID field to retrieve the HubSpot company that has an ERP Account ID property value of A1234:
https://api.hubapi.com/crm/v3/objects/companies/A1234?archived=false&idProperty=erp_account_id&hapikey=YOURHUBSPOTAPIKEY
Pretty easy, right?
Final Thoughts
While the idProperty designation is certainly an integration game-changer, there is a caveat – currently, this designation cannot be made on a field on the Contact object. Email and Contact ID are the only true ID fields for contacts. You can certainly create a custom field to hold external IDs, there will just be no native API functionality there and no guarantees on uniqueness.
To recap, the idProperty field designation:
- Can only be done via the API
- Currently can be done on any object (including custom objects) except the Contact object
- Has native API GET, PATCH, DELETE functionality
- Can speed up and optimize integration code logic, generally improving your custom integrations with third-party systems
- Can be utilized with any HubSpot account tier level
UPDATE: You can now configure ID Property fields via the API and UI! In Settings, navigate to Properties -> Create Property. Then, enter the Label and choose the Group and click Next to select the property type. If single-line text or Number is chosen, a checkbox will appear, allowing you to require values as unique:
Interested in joining the obo team?
