Summary

An iPaaS.com Customer can be transferred to HubSpot as a HubSpot contact, either automatically when the iPaaS.com event system is configured to send customer changes, or on demand from the iPaaS.com Manual Sync page. A single collection handles both creating and updating the contact, and which of the two happens is decided by whether the iPaaS.com Customer is already linked to a HubSpot contact. Because a HubSpot contact holds a single address, the customer's primary billing address is flattened onto the contact's address properties, and the customer's relationships travel with it as HubSpot associations.

ID Format

Manual Sync ID Format

Enter the iPaaS.com Customer id on the iPaaS.com Manual Sync page to transfer that customer to HubSpot.

External ID Format

The HubSpot contact id assigned when the contact is created is recorded as the external-id link on the iPaaS.com Customer. That link is what routes every later change to the same HubSpot contact as an update rather than creating a second contact.

For an association, the link recorded is a composite of the owning HubSpot record id, the object type of the record the association points at, the associated record's HubSpot id, and the association's object type, joined with pipe characters.

The iPaaS.com related-to id supplied to the association collection may itself carry a HubSpot association type appended to it, separated by a pipe character. This is written by the opposite-direction collection to satisfy the iPaaS.com requirement for a unique combination of relationship type and related-to id, because one iPaaS.com relationship can produce several HubSpot associations. The mappings read only the first segment of that value when resolving the target record, so an id in this format resolves correctly. Other integrations that consume iPaaS.com relationship data must account for the same id format.

Deleted Record Support

Outbound delete is not supported. Deleting a customer in iPaaS.com does not delete or archive the linked HubSpot contact, delete mappings are not included in the default templates, and deletions do not propagate in any form. Removing a relationship in iPaaS.com likewise does not remove the association in HubSpot. Removing a contact in HubSpot is a manual action performed under a supervised process.

Custom Field Support

Custom fields are supported on Add/Update HubSpot Contact FROM iPaaS.com. A HubSpot contact property is set by creating an iPaaS.com custom field whose name matches the contact property label in HubSpot, then mapping the preferred source data to that custom field. The HubSpot property must be created manually beforehand:

In the iPaaS.com HubSpot subscription's custom fields page, add a Customer module custom field.
In HubSpot, go to Settings > Data Management > Properties and select Create Property.
Provide the desired property name as a Contact object type property, and select the desired group.
On the Field type tab, select Single-line text as the field type before selecting Create.
In this mapping collection, create a mapping to the custom field with the preferred source data.

Source data must suit the HubSpot property's field type, otherwise unexpected errors may occur in HubSpot:

Text: values can typically be provided as-is.
Number: only accepts numeric values.
Date: requires source data to be provided in Epoch time format.
Boolean/Checkbox: set with the value true or false, where true means Yes.
Multi-select: requires a semicolon separator in the source data when setting multiple values — a source value of first;second sets two values.

The Favourite Sports mapping ships as a worked example of this pattern, and completes the round trip with the Interested Sports mapping on Add/Update HubSpot Contact TO iPaaS.com.

Placeholder value — replace during implementation: the Interested Sports custom field and the Favourite Sports HubSpot property are example fields from a demonstration environment. Replace them with your own iPaaS.com custom field and the matching HubSpot property label.

Custom fields are not supported on Add/Update HubSpot Contact Association FROM iPaaS.com. The integration does not read iPaaS.com Relationship custom fields in this direction and does not write HubSpot custom properties from that collection. Relationship custom fields can be mapped in the TO iPaaS.com direction only.

Mapping Collection Status

Status: Enabled. Both the contact collection and the contact association collection ship in the default HubSpot template and are enabled.

Trigger Events: These are FROM iPaaS.com collections, so they are driven by iPaaS.com outbound triggers, which subscribers or their MiSP enable under Outbound Data Flows in the subscription configuration. Subscribe to the iPaaS.com Customer add and update events that should dispatch a transfer. No automatic transfers occur until those subscriptions are enabled. Manual Sync is available on the parent collection regardless. Whether a given transfer creates or updates a HubSpot contact is decided by the external-id link, not by which event was raised. The association collection has no trigger of its own — it runs whenever its parent customer transfers, by either method.

Duplicate or Conflicting Mappings

When a customer that is not yet linked is transferred, HubSpot is searched for an existing contact already using the same email address. If a match is found, the contact is linked automatically and the transfer proceeds as an update instead of a create. The customer's addresses and other child objects are not linked by that match, and may encounter transfer errors depending on the type of data conflict occurring. A customer transferred without an email address cannot be matched this way, so it creates a new HubSpot contact even where a similar contact already exists there.

HubSpot uses the email address to deduplicate contacts. Where a customer carries no email address, or carries a different address from the one already held in HubSpot, this can produce two HubSpot records for one person. If a merge is performed in HubSpot to resolve this, the resulting record should be the one linked to iPaaS.com so it remains usable for future transfers.

The other collections that operate on the same or a closely related entity are:

Add/Update HubSpot Contact TO iPaaS.com: the opposite-direction collection that imports HubSpot contacts into iPaaS.com. Plan the mappings in both directions together, and decide which system is the source of truth for a given field, before enabling a bi-directional contact sync.
Add HubSpot Company FROM iPaaS.com and Update HubSpot Company FROM iPaaS.com: write iPaaS.com companies to HubSpot companies, which are a separate object. The Company property on a contact is a text property on the contact record and does not by itself create a HubSpot company.

Supported Child Collections

Add/Update HubSpot Contact Association FROM iPaaS.com: writes the customer's iPaaS.com relationships to HubSpot as contact and company associations. It runs as part of the customer's transfer. Each association is resolved through the related record's own external-id link, so an association is only written once both ends of the relationship exist in HubSpot. A relationship whose other end has not been transferred yet is skipped; this is a skip, not an error.

System Caveats

HubSpot Caveats

A HubSpot contact holds a single address: the standard contact fields contain one address entry, which is why one iPaaS.com address is selected rather than all of them. Change the address mappings as needed to use different information for the HubSpot address.
Email de-duplication: HubSpot uses the email address to deduplicate contacts, so a customer transferred without an email address may create a contact that later duplicates.
Single category property: only one HubSpot property represents the contact category, so where an iPaaS.com Customer carries several category assignments only one of them is used — the last assignment processed becomes the final property value in HubSpot. Category assignment is best suited to a single category assignment per customer.
Contact category property: the property named in the Contact Category Field Name setting must exist in HubSpot beforehand as a Dropdown select property on the Contact object, with at least one option defined.
Property field types: a value that does not match the HubSpot property's field type is rejected by HubSpot. See the field-type rules under Custom Field Support.
Both records must exist before an association: HubSpot requires the originating record and the target record to be identified before an association can be created. This is why the association collection's filter skips a relationship whose target has not transferred.
Custom association labels cannot be created from iPaaS.com: HubSpot separates its own built-in association labels from custom labels defined in the account. Only the basic contact and company associations are written from iPaaS.com. A custom label that originated in HubSpot is preserved on a round trip, but a new custom label cannot be introduced from the iPaaS.com side.
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

One address is sent: the address, city, state, country, postal code, and phone mappings read the iPaaS.com Customer's first address flagged as primary billing. A customer with no address flagged as primary billing supplies no value to those properties. An iPaaS.com Customer may hold many addresses, but only the primary billing address is written to HubSpot.
Categories are opt-in: the customer's category assignments transfer only when the Contact Category Field Name subscription setting names a HubSpot property. Leaving that setting empty disables contact category processing entirely, and no error is raised.
Category resolution: only iPaaS.com categories that carry a HubSpot link are emitted as HubSpot category values.
One relationship can map to several associations: this is why an iPaaS.com related-to id may carry the association type appended to it, as described under External ID Format.
The target record must be transferred first: a relationship whose target customer or company is not yet linked to a HubSpot record is skipped rather than transferred as a prerequisite.

Setup Requirements

iPaaS.com Configuration

Enable the iPaaS.com Customer add and update outbound triggers under Outbound Data Flows on the subscription. No automatic transfers occur until they are enabled.
Create any Customer module custom fields whose values should reach HubSpot contact properties, naming each one to match the HubSpot property label.
Populate the Contact Category Field Name subscription setting if contact categories should transfer.

HubSpot Configuration

Create each HubSpot contact property that a custom field mapping targets, before the first transfer. See Custom Field Support for the steps and the field-type rules.
Create the contact category property named in Contact Category Field Name as a Dropdown select property with at least one option defined.
Confirm the connected HubSpot account can create and edit contacts and can create associations.

Authentication and connection setup are covered in HubSpot Installation Instructions and HubSpot Connections and Settings.

Integration Flow

An iPaaS.com customer add or update, or a manual sync, dispatches the customer transfer.
The integration resolves whether the iPaaS.com Customer is already linked to a HubSpot contact from the saved external-id link. When there is no link, HubSpot is searched for a contact already using the customer's email address; a match is linked automatically and the transfer proceeds as an update.
The mapped contact properties are assembled, including any custom field values and the primary billing address flattened onto the contact's address properties.
When the iPaaS.com Customer carries category assignments and the Contact Category Field Name setting is populated, each category value is added to the HubSpot contact category property first, so the value exists before the contact references it.
When there is still no link, the HubSpot contact is created from the assembled properties and the new HubSpot contact id is saved as the external-id link. When a link exists, the linked HubSpot contact is updated in place.
On a create, the new contact is read back from HubSpot to establish which contact and company associations it already carries.
The customer's relationships are written to HubSpot as contact and company associations through the association child collection, skipping any association the contact already has.
Only the values the transfer actually has are sent. Properties that are not mapped are never blanked.

Mappings

Add/Update HubSpot Contact FROM iPaaS.com (Parent)

iPaaS.com data type: Customer

This collection writes an iPaaS.com Customer to HubSpot as a contact, creating the contact when the customer is not yet linked to one and updating the linked contact when it is.

Mapping Type	Source Field (iPaaS.com)	Destination Field (HubSpot)	Description
Field	Id	Id	Required. The iPaaS.com Customer id, used to establish and maintain the external-id link between the iPaaS.com Customer and the HubSpot contact. The link is what allows a later transfer to update the same HubSpot contact rather than creating a second one, so this mapping should not be removed.
Field	EmailAddress	Email	Recommended. The iPaaS.com Customer email address, written to the HubSpot contact Email property. HubSpot requires at least one of email, firstname, or lastname when a contact is created, and uses the email address as the primary unique identifier to avoid duplicate contacts. This is also the value the integration uses to prevent duplicates: a new customer is matched against existing HubSpot contacts by email, and a match is linked automatically so the transfer proceeds as an update instead of a create. A customer transferred without an email address cannot be de-duplicated on a later transfer.
Field	FirstName	FirstName	Recommended. The iPaaS.com Customer first name, written to the HubSpot contact FirstName property. HubSpot requires at least one of email, firstname, or lastname when a contact is created; this mapping is one of the three that satisfy that requirement.
Field	LastName	LastName	Recommended. The iPaaS.com Customer last name, written to the HubSpot contact LastName property. HubSpot requires at least one of email, firstname, or lastname when a contact is created; this mapping is one of the three that satisfy that requirement.
Dynamic Formula	`FieldFromFirstMatch(Addresses, "IsPrimaryBilling == true", "PhoneNumber")`	Phone	Optional. Reads the phone number from the customer's first address flagged as primary billing and writes it to the HubSpot contact Phone property. A HubSpot contact holds a single address, so the template consistently reads the primary billing address for every address-derived property. A customer with no address flagged as primary billing supplies no phone number. Change this mapping as needed if the phone number your subscription should publish to HubSpot lives elsewhere on the customer.
Field	Company	Company	Optional. The company name recorded on the iPaaS.com Customer, written to the HubSpot contact Company property. This is a text property on the contact record itself; it does not by itself create or link a HubSpot company object. Company records are written by the separate HubSpot Company collections, and a contact's association to a company is written by the Contact Association child collection.
Dynamic Formula	`FieldFromFirstMatch(Addresses, "IsPrimaryBilling == true", "Address1");`	Address	Optional. Reads the street address from the customer's first address flagged as primary billing and writes it to the HubSpot contact Address property. Standard HubSpot contact fields contain a single address entry, so the template searches for the primary billing address to provide this information. A customer with no primary billing address supplies no value. Change this mapping as needed to use a different address on the customer.
Dynamic Formula	`FieldFromFirstMatch(Addresses, "IsPrimaryBilling == true", "City")`	City	Optional. Reads the city from the customer's first address flagged as primary billing and writes it to the HubSpot contact City property. Keep this mapping aligned with the other address-derived mappings, so that every part of the HubSpot address comes from the same iPaaS.com address.
Dynamic Formula	`FieldFromFirstMatch(Addresses, "IsPrimaryBilling == true", "Region")`	State	Optional. Reads the region from the customer's first address flagged as primary billing and writes it to the HubSpot contact State property. iPaaS.com stores the state or province as Region; HubSpot names the same concept State.
Dynamic Formula	`FieldFromFirstMatch(Addresses, "IsPrimaryBilling == true", "Country")`	Country	Optional. Reads the country from the customer's first address flagged as primary billing and writes it to the HubSpot contact Country property. The value transfers as it is stored in iPaaS.com, so keep country naming consistent across source systems if HubSpot reporting groups contacts by country.
Dynamic Formula	`FieldFromFirstMatch(Addresses, "IsPrimaryBilling == true", "PostalCode")`	Zip	Optional. Reads the postal code from the customer's first address flagged as primary billing and writes it to the HubSpot contact Zip property.
Field	Interested Sports	Favourite Sports	Optional. Copies the iPaaS.com Interested Sports custom field to the HubSpot contact property labelled Favourite Sports.
Dynamic Formula	`return await GetHubSpotCategoryValuesFromCategories(Categories);`	CustomerCategories	Optional. Combines the customer's iPaaS.com category assignments into a list of HubSpot category values and supplies them to the CustomerCategories control field, which writes to the HubSpot contact property named in the Contact Category Field Name subscription setting.

Favourite Sports

Optional. Copies the iPaaS.com Interested Sports custom field to the HubSpot contact property labelled Favourite Sports. This mapping ships as a worked example of writing a custom property to HubSpot: a HubSpot contact property is set by creating an iPaaS.com custom field whose name matches the contact property label in HubSpot, then mapping your preferred source data to it. The HubSpot property must be created manually beforehand under Settings > Data Management > Properties as a Contact object property. Provide source data appropriate to the property's field type — text as-is; number fields accept numeric values only; date fields require Epoch time format; boolean fields are set with true or false; multi-select values require a ; separator, so a source value of first;second sets two values. It completes the round trip with the Interested Sports mapping on Add/Update HubSpot Contact TO iPaaS.com.

CustomerCategories

Optional. Combines the customer's iPaaS.com category assignments into a list of HubSpot category values and supplies them to the CustomerCategories control field, which writes to the HubSpot contact property named in the Contact Category Field Name subscription setting. Create that property in HubSpot beforehand as a Dropdown select field type on the Contact object, with at least one category name defined. Only iPaaS.com categories that resolve to a HubSpot value are emitted.

Because only one HubSpot property holds the category designation, only one of the iPaaS.com category assignments is used where a customer carries several — the last assignment processed becomes the final property value in HubSpot. Category assignment is best suited to a single category assignment per customer. Leave Contact Category Field Name empty to fully disable category assignment processing.

Add/Update HubSpot Contact Association FROM iPaaS.com (Child)

iPaaS.com data type: Customer Relationship

This collection writes the iPaaS.com Customer's relationships to HubSpot as contact and company associations, running as part of the customer's own transfer.

Mapping Filter

if (string.IsNullOrEmpty(RelatedToId))
  return false;var customerId = await GetExternalIdAsync(RelatedToId.Split("|")[0], "Customer", SpaceportSystemId);
if(customerId != null){
return true;
}
else{
var companyId = await GetExternalIdAsync(RelatedToId.Split("|")[0], "Company", SpaceportSystemId);
if(companyId != null)
    return true;
}
return false;

Filter Description. The filter decides whether a relationship is worth sending to HubSpot, and it lets through only relationships whose other end already exists in HubSpot. A relationship with an empty related-to id is skipped immediately, because there is no target to associate to. Otherwise the filter takes the first segment of the related-to id — the iPaaS.com id of the record at the other end, before any appended HubSpot association type — and looks for a Customer in iPaaS.com linked to a HubSpot contact. If it finds one, the relationship passes and the association is written. If it does not, it looks for a Company linked to a HubSpot company using the same value, and the relationship passes if that is found. If neither a linked customer nor a linked company exists, the relationship does not pass and is skipped. A skipped relationship is not an error and produces no entry in the Error Logs: it simply means the record at the other end has not reached HubSpot yet, and the association is written on the next transfer of the parent customer once it does.

It is not advised to alter the mappings in this collection, as they are required to support the HubSpot associations.

Mapping Type	Source Field (iPaaS.com)	Destination Field (HubSpot)	Description
Field	IsPrimary	IsPrimary	Whether the iPaaS.com relationship is the primary one for the customer, written as the association's primary designation in HubSpot. Optional: HubSpot does not require it in order to create an association. Mapping it keeps the primary designation aligned between the two systems, so it is worth leaving in place.
Dynamic Formula	`var customerId = await GetExternalIdAsync(RelatedToId.Split("\|")[0], "Customer", SpaceportSystemId); if(customerId != null){ return customerId; } else{ return await GetExternalIdAsync(RelatedToId.Split("\|")[0], "Company", SpaceportSystemId); }`	RelatedToId	Required. The HubSpot record the association points at.
Field	Type	Type	The iPaaS.com relationship type, written as the association's label in HubSpot. Recommended: HubSpot allows a basic association between two records to be created with no label at all, so a label is not strictly required — but the type is what preserves an association's original identity across a round trip. When an association originated in HubSpot, was imported to iPaaS.com, and transfers back through this collection, the type is what carries its original association type home. Only basic template HubSpot associations for contacts and companies can be uploaded FROM iPaaS.com. HubSpot separates its own built-in association labels from custom labels defined within an account, and a new custom label cannot be introduced from the iPaaS.com side — though a custom label that originated in HubSpot is preserved on a round trip.

RelatedToId

The HubSpot record the association points at. This value is required — HubSpot requires the target record to be identified before an association between two records can be created.

The formula reads the first segment of the iPaaS.com related-to id and resolves it to a linked HubSpot record: it looks first for a HubSpot contact linked to that iPaaS.com Customer, and falls back to a HubSpot company linked to that iPaaS.com Company when no contact is linked.

Reading only the first segment matters, because the related-to id may carry a HubSpot association type appended to it, separated by a pipe character. That append is written by the opposite-direction collection to satisfy the iPaaS.com requirement for a unique combination of relationship type and related-to id, since one iPaaS.com relationship can produce several HubSpot associations. Taking the first segment strips the appended type back off, so the id resolves to the right record on the way home. Other integrations that consume iPaaS.com relationship data must account for the same id format.

If the target record is not linked to a HubSpot record, the mapping filter on this collection skips the relationship before this mapping runs. Nothing is written and no error is raised. Once the target customer or company has transferred to HubSpot, the next transfer of the parent customer writes the association normally.

Error Handling

The errors these collections can raise are catalogued, with their causes and resolutions, in HubSpot Error Messages. Rather than repeat them here, the entries most relevant to contact transfers are:

HubSpot API Communication: covers the messages raised when HubSpot rejects or cannot receive a contact write, 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.
Property value rejections: raised when a value does not suit the HubSpot property's field type — for example a non-numeric value sent to a Number property, or a date sent to a Date property in a format other than Epoch time. Correct the source data or the property's field type, then re-sync the customer.
Contact category property errors: raised when the property named in Contact Category Field Name does not exist in HubSpot, or is not a Dropdown select property with at least one option. Correct the property in HubSpot, or clear the setting to disable category processing, then re-sync the customer.
Child object conflicts after an email match: when an unlinked customer is matched to an existing HubSpot contact by email address, the customer's addresses and other child objects are not linked by that match and may raise transfer errors depending on the type of data conflict occurring.

All failures are reported under Dashboard, Integration Monitoring, Error Logs. A relationship skipped by the association collection's mapping filter is not a failure and does not appear there.

Testing & Validation

Test Scenarios

Create a new iPaaS.com Customer that has never been transferred and that carries an email address not present in HubSpot, then manually sync it by its iPaaS.com Customer id. Confirm a new HubSpot contact is created and that the iPaaS.com Customer now carries the HubSpot contact id as its external-id link.
Change the first name, last name, or email address on that same iPaaS.com Customer and re-sync. Confirm the existing HubSpot contact is updated in place and no second contact appears.
Create a second iPaaS.com Customer using the email address of a contact that already exists in HubSpot and is not yet linked, then sync. Confirm the existing HubSpot contact is linked and updated rather than duplicated.
Flag an address on an iPaaS.com Customer as primary billing and re-sync. Confirm the address, city, state, postal code, country, and phone number reach the HubSpot contact. Remove the primary billing flag and confirm no address is sent.
Create a HubSpot contact property, create a matching iPaaS.com Customer custom field named after that property's label, map it, populate a value, and re-sync. Confirm the value reaches the HubSpot property. Repeat with a value that does not suit the property's field type and confirm the failure is reported under Dashboard, Integration Monitoring, Error Logs.
Add a relationship between the iPaaS.com Customer and a record whose counterpart has not been transferred to HubSpot, then sync. Confirm the association is skipped without an error and without an entry in the Error Logs. Transfer the related record, re-sync the customer, and confirm the association is created.
Populate the Contact Category Field Name setting with a valid HubSpot Dropdown select property, assign a category to the iPaaS.com Customer, and re-sync. Confirm the category value appears on the HubSpot contact property. Assign a second category and confirm only one value results. Clear the setting and confirm category processing stops with no error raised.
Edit a HubSpot contact property that no mapping targets, then re-sync the customer. Confirm the value is left as it is.

Validation Checklist

A first transfer creates a HubSpot contact, or links an existing one by email address, and records the external-id link.
A second transfer of the same customer updates it rather than creating a duplicate.
Fields left unmapped on the HubSpot contact are not blanked by a transfer.
Only the primary billing address reaches HubSpot.
Custom field values reach the HubSpot properties whose labels match the iPaaS.com custom field names.
Category values transfer only when Contact Category Field Name names a valid property, and only one assignment results.
Associations appear only once both ends of the relationship exist in HubSpot.
A relationship whose target has not transferred is skipped silently, with no entry in the Error Logs.
Errors appear under Dashboard, Integration Monitoring, Error Logs.

Additional Notes

Customer addresses as separate records are out of scope. A HubSpot contact holds a single address, so addresses are written as contact properties rather than as child address records.
HubSpot companies are created and updated by the separate HubSpot Company collections. The Company property on a contact is a text property and does not by itself create a HubSpot company.
At the time this documentation was written, only one iPaaS.com category assignment per customer reaches HubSpot when several are provided, because a single HubSpot property holds the category designation. The last assignment processed becomes the final property value.
At the time this documentation was written, only the primary billing address transfers, because a HubSpot contact holds a single address.
At the time this documentation was written, when an outgoing customer is matched to an existing HubSpot contact by email address, the customer's addresses and other child objects are not linked by that match and may encounter transfer errors.
At the time this documentation was written, custom association types from iPaaS.com are not supported. Only the basic template HubSpot associations for contacts and companies can be written from iPaaS.com. An association that originated in HubSpot and was transferred to iPaaS.com retains its original association type when it transfers back.
At the time this documentation was written, custom fields are not supported on Add/Update HubSpot Contact Association FROM iPaaS.com. Relationship custom fields can be mapped in the TO iPaaS.com direction only.

iPaaS.com to HubSpot Contact Mapping Documentation