Summary
A category designation held on a HubSpot contact or company can be transferred to iPaaS.com as a customer category. HubSpot has no built-in customer category object, so the designation is held in an ordinary HubSpot property, and this collection turns each of that property's values into an iPaaS.com customer category record. Which HubSpot property is read is controlled by the Contact Category Field Name and Company Category Field Name subscription settings; leaving both empty disables category processing entirely.
ID Format
Manual Sync ID Format
The value transferred is a HubSpot property value rather than a HubSpot record, so the id supplied is the property value followed by a suffix identifying which kind of record the property belongs to:
_customer: the value came from the HubSpot contact property named in Contact Category Field Name.
_company: the value came from the HubSpot company property named in Company Category Field Name.
To transfer a contact property value of "Gold Customer", supply gold customer_customer. To transfer a company property value of "Gold Customer", supply gold customer_company.
External ID Format
The external id that links an iPaaS.com customer category back to HubSpot takes the same form as above: the property value with the _customer or _company suffix appended. That suffix is what records which of the two subscription settings the value originated from.
Deleted Record Support
Deleted records are not supported. Removing a value from the HubSpot property does not delete the corresponding iPaaS.com customer category, delete mappings are not included in the default templates, and deletions do not propagate in any form. Removing a customer category in iPaaS.com is a manual action performed under a supervised process.
Custom Field Support
Custom fields are not supported for this collection. A custom field mapping added here does not populate a value on the iPaaS.com customer category.
Mapping Collection Status
Status: Enabled. Sync type is Add/Update, in the TO iPaaS.com direction.
Trigger Events: HubSpot records are not transferred automatically by webhook. Transfers are driven by scheduled polling: the integration records the time of the last successful run and, on each poll, asks HubSpot for the records changed since that time. A category/customer/poll event can be scheduled to sweep the property for additional values and add them to iPaaS.com, which is the recommended approach for an initial load. The poll scopes may also be sent manually. To transfer an individual value, a category/customer/created or category/customer/updated event can be sent. Categories are also transferred automatically as a prerequisite when a contact or company that carries a category is transferred TO iPaaS.com.
Duplicate or Conflicting Mappings
No subscriber-selectable duplicate-handling option is presented for this collection. When a contact or company is transferred TO iPaaS.com and carries a category, the integration first tries to link the category to an existing iPaaS.com customer category with the same name, and only creates a new category when no name match is found. This name matching is what keeps repeated transfers of the same designation from producing duplicate iPaaS.com categories.
The opposite-direction collection that operates on the same entity is Add/Update HubSpot Customer Category FROM iPaaS.com, which writes iPaaS.com categories back to the HubSpot property as selectable values, and is covered in iPaaS.com to HubSpot Customer Category Mapping Documentation. Because categories transfer in both directions, subscribers or their MiSP should decide which system is authoritative for the category list before enabling both.
Unmapped Field Overwrite Risk
When this collection updates an existing iPaaS.com customer category, the update replaces the record with the values supplied here. An iPaaS.com field that has no mapping in this collection is therefore cleared when the category is updated from HubSpot.
Only Name is mapped. The iPaaS.com customer category also carries a Description, which has no mapping in this collection — so a description entered directly in iPaaS.com is removed the next time that category is updated from HubSpot. Any other value held on the iPaaS.com customer category and left unmapped here is replaced in the same way.
To preserve a field that HubSpot has no equivalent for, add a mapping for it using the DestinationValue source. That writes back the value already stored on the iPaaS.com record instead of clearing it. This is the same consideration that applies across bi-directional transfers generally: map every value you wish to preserve. Subscribers or their MiSP should plan their mappings with this in mind, and consult their MiSP for guidance on preserving values in bi-directional transfers.
System Caveats
HubSpot Caveats
The HubSpot property must exist first: create it as a Dropdown Select property with at least one value defined before transferring. A property with no values gives the integration nothing to read.
The settings hold the property label: the integration matches on the property's label, not its internal name.
Only property values become categories: iPaaS.com categories are built from the HubSpot property's defined values, so a designation that is not a value on that property cannot transfer.
Rate limiting: at the time this documentation was written, the integration does not wait and retry when HubSpot throttles it. A throttled transfer fails and must be re-run. The failure is reported under Dashboard, Integration Monitoring, Error Logs.
iPaaS.com Caveats
An empty setting silently skips: the Contact Category Field Name and Company Category Field Name subscription settings are configured on the iPaaS.com HubSpot subscription. If the relevant setting is blank, category processing for that record type does not run and no error is raised.
No category hierarchy: a HubSpot property is a flat list of values, so no parent or child relationship between categories is transferred.
Setup Requirements
HubSpot Configuration
Create the contact category property, the company category property, or both, as a Dropdown Select property with at least one value defined.
Confirm the connected HubSpot account can read those properties.
iPaaS.com Configuration
Populate the Contact Category Field Name subscription setting with the label of the HubSpot contact property that holds the category designation, and the Company Category Field Name setting with the label of the equivalent company property. Populate only the settings for the record types whose categories should transfer.
Leave both settings empty to disable category assignment processing entirely, including the pre-processing that transfers a contact's or company's dependent categories ahead of the record itself. Subscribers or their MiSP who do not want categories to move between the systems can additionally remove the mappings to the Categories field in the Company TO iPaaS.com collections, along with this collection's mapping, to prevent category transfer entirely.
Authentication and connection setup are covered in HubSpot Installation Instructions and HubSpot Connections and Settings.
Integration Flow
A scheduled poll, a manually sent poll or category event, or the transfer of a contact or company that carries a category, dispatches the category transfer.
The integration reads the Contact Category Field Name and Company Category Field Name subscription settings to determine which HubSpot property holds the designation for the record type in question. When the relevant setting is empty, processing stops here and no error is raised.
The named HubSpot property is resolved by its label, and its defined values are read.
Each value is combined with the _customer or _company suffix to form the external id that links the resulting iPaaS.com customer category back to its HubSpot origin.
The integration looks for an iPaaS.com customer category already linked to that external id. Where none exists, it looks for an existing iPaaS.com customer category with the same name and links it rather than creating a duplicate.
When a link is found, the linked iPaaS.com customer category is updated with the values this collection supplies, replacing the record. When no link and no name match is found, a new iPaaS.com customer category is created and the external id is recorded against it.
Where the transfer began with a contact or company, its categories are processed first, so each category exists in iPaaS.com before the record that references it is transferred.
Mappings
Add/Update HubSpot Customer Category TO iPaaS.com (Parent)
iPaaS.com data type: Customer Category
This collection creates or updates an iPaaS.com customer category from a value defined on the HubSpot contact or company property named in the category subscription settings.
Mapping Type | Source Field (HubSpot) | Destination Field (iPaaS.com) | Description |
Field | CategoryName | Name | Required. Sets the iPaaS.com customer category's name from the HubSpot property value being transferred. The value comes from the HubSpot contact or company property named in the Contact Category Field Name and Company Category Field Name subscription settings, so the category names that appear in iPaaS.com are the values defined on that property. Name is the only value iPaaS.com requires in order to create or update a customer category, and it is also what the integration matches on: when a contact or company carrying a category is transferred TO iPaaS.com, an existing iPaaS.com category with the same name is linked rather than a duplicate being created. Removing this mapping leaves the transfer with nothing to identify the category by. |
Error Handling
The errors this collection can raise are catalogued, with their causes and resolutions, in HubSpot Error Messages. Rather than repeat them here, the entries most relevant to category transfers are:
HubSpot API Communication: covers the messages raised when HubSpot rejects or cannot answer a read of the category property, including the rate limit case. At the time this documentation was written, the integration does not wait and retry when HubSpot throttles it, so a throttled transfer fails and must be re-run.
Category property errors: raised when the property named in Contact Category Field Name or Company Category Field Name does not exist in HubSpot, or is not a Dropdown Select property with at least one value defined. Correct the property in HubSpot, or clear the setting to disable category processing for that record type, then re-run the transfer.
All failures are reported under Dashboard, Integration Monitoring, Error Logs.
Testing & Validation
Test Scenarios
Populate Contact Category Field Name with the label of a HubSpot contact Dropdown Select property that has at least one value, then run a category/customer/poll. Confirm an iPaaS.com customer category is created for each value on that property.
Transfer an individual value by sending a category/customer/created event with the property value and the _customer suffix, for example gold customer_customer. Confirm the matching iPaaS.com customer category is created and carries that external id.
Repeat scenario 2 against the company property using the _company suffix, and confirm the resulting iPaaS.com customer category carries the company-suffixed external id.
Create an iPaaS.com customer category by hand with the same name as a HubSpot property value, then transfer a contact carrying that designation. Confirm the existing iPaaS.com category is linked by name and no duplicate is created.
Enter a Description on an iPaaS.com customer category that is linked to HubSpot, then re-transfer that category. Confirm the description is cleared, which demonstrates the replace behaviour described under Unmapped Field Overwrite Risk. Add a DestinationValue mapping for the description, re-transfer, and confirm the description is now preserved.
Clear both category field name settings and transfer a contact and a company that carry a category. Confirm no category processing occurs and no error is raised.
Remove a value from the HubSpot property and re-run a poll. Confirm the corresponding iPaaS.com customer category is not deleted.
Validation Checklist
Each value on the named HubSpot property produces an iPaaS.com customer category.
The external id on each iPaaS.com customer category carries the _customer or _company suffix matching the property it came from.
A category name that already exists in iPaaS.com is linked rather than duplicated.
An iPaaS.com field left unmapped in this collection is cleared on update unless it is mapped with DestinationValue.
An empty category field name setting stops processing for that record type without raising an error.
Removing a value in HubSpot leaves the iPaaS.com customer category in place.
Errors appear under Dashboard, Integration Monitoring, Error Logs.
Additional Notes
At the time this documentation was written, deleted records are not supported for this collection. Removing a value from the HubSpot property does not remove the iPaaS.com customer category it produced.
At the time this documentation was written, category hierarchies are out of scope. A HubSpot property is a flat list of values, so no parent or child relationship between categories transfers.
At the time this documentation was written, an iPaaS.com category description is not preserved by this collection unless it is explicitly mapped. See Unmapped Field Overwrite Risk.
At the time this documentation was written, only one HubSpot property holds the category designation for each record type. When a category assignment travels back FROM iPaaS.com to HubSpot, only one assignment can be represented. Subscribers or their MiSP running categories in both directions should read the limitations in iPaaS.com to HubSpot Customer Category Mapping Documentation before designing around multiple categories per customer.
Writing categories to HubSpot is out of scope here; that direction is handled by Add/Update HubSpot Customer Category FROM iPaaS.com.