Summary
A HubSpot contact can be imported into iPaaS.com as a Customer record, linked by the HubSpot contact id saved as the external id. A single collection handles both the create and the update, and which one happens is decided by whether the HubSpot contact is already linked to an iPaaS.com Customer. The contact's address and its company and contact associations travel with it through two child collections as part of the same transfer.
ID Format
Manual Sync ID Format
Enter the HubSpot contact id on the iPaaS.com Manual Sync page to import that contact into iPaaS.com. The child collections have no Manual Sync id of their own — the address and the associations are transferred only as part of their parent contact, using the HubSpot contact id.
External ID Format
The HubSpot contact id is recorded as the external-id link on the iPaaS.com Customer, so subsequent transfers update the same Customer rather than creating a duplicate.
The link recorded against an iPaaS.com Customer Relationship 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 link recorded against an iPaaS.com Customer Address is the HubSpot contact id joined to the id of the mapping collection that produced the address, separated by a pipe character. Because a HubSpot contact carries only one address but a subscription can define more than one address mapping collection against it, including the collection in the link keeps each mapping collection's address separately identifiable on the same contact.
Deleted Record Support
Deleted record transfers are not supported for any of these collections. Deleting a contact in HubSpot does not delete or deactivate the linked iPaaS.com Customer, removing an association in HubSpot does not remove the linked iPaaS.com Customer Relationship, and clearing an address in HubSpot does not remove the linked iPaaS.com Customer Address. Delete mappings are not included in the default templates and deletions do not propagate in any form. Removing a record in iPaaS.com is a manual action performed under a supervised process.
Custom Field Support
Custom fields are supported on Add/Update HubSpot Contact TO iPaaS.com. HubSpot contact properties beyond the standard set are read into iPaaS.com Customer custom fields. Most HubSpot contact properties are not exposed as directly selectable source fields, so importing an additional one requires a Dynamic Formula that searches for the property by its property label. The template includes two such label-based mappings, Job Title and Interested Sports. Two further custom-field mappings, HubSpot Owner Id and HubSpot Owner Email, populate iPaaS.com custom fields from the contact's owner assignment rather than by a property-label lookup.
To add a custom field of your own, create a Customer-module custom field on the iPaaS.com HubSpot subscription's custom fields page, then add a Dynamic Formula mapping to it that reads the HubSpot property by label. The Job Title mapping is the worked example to copy: the formula supplies the property label to search for and the contact object type, and returns that property's value from the contact. The property must already exist in HubSpot under Settings > Data Management > Properties as a Contact object property. The label match is not case-sensitive, and the formula returns no value if the label does not match a property or if the contact has no value for it.
The Interested Sports mapping ships as a worked example of this pattern, and round-trips back to HubSpot through the Favourite Sports mapping on Add/Update HubSpot Contact FROM 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 TO iPaaS.com or Add/Update HubSpot Contact Address TO iPaaS.com. Neither child collection reads a HubSpot custom property. iPaaS.com Relationship custom fields are, however, available as destinations on the association child in this direction, and the template demonstrates that with two of its mappings; subscribers or their MiSP may add further mappings to iPaaS.com Relationship custom fields to record more about a relationship. That is not available in the opposite direction.
Mapping Collection Status
Status: Enabled. The parent contact collection and both child collections ship in the default HubSpot template and are enabled.
Trigger Events: At the time this documentation was written, HubSpot contacts are not transferred to iPaaS.com automatically by webhook. A HubSpot contact change is not delivered to iPaaS.com on its own, and the customer/created and customer/updated scopes do not produce an automatic contact transfer. Contacts are transferred on a schedule using a record-polling approach instead: subscribers or their MiSP configure a scheduled contact/poll event in the iPaaS.com event system using the Webhook (poll request) event type. After each polling event the current time is saved to the HubSpot subscription in iPaaS.com, and the next polling event uses that timestamp as a "last modified date is greater than" filter, so only contacts modified since the previous poll are transferred. No automatic transfers occur until a polling schedule is configured. A contact/poll request may also be sent manually, and Manual Sync is available on the parent collection regardless. The child collections have no trigger of their own and run whenever the parent contact transfers, by either method.
Duplicate or Conflicting Mappings
The other collection that operates on the same entity is Add/Update HubSpot Contact FROM iPaaS.com, the opposite-direction collection that writes iPaaS.com customers to HubSpot. When both directions are enabled, the guidance under Unmapped Field Overwrite Risk below applies. Review the filters and the Add/Update settings across the collections, and decide which system is the source of truth for a given field, before enabling a bi-directional contact sync.
Add/Update HubSpot Company TO iPaaS.com imports HubSpot companies, which are a separate object from contacts. A contact's company association is imported by the Contact Association child collection, not by the parent contact collection, so the two do not overlap.
When a new contact is transferred, iPaaS.com is searched for an existing customer already using the same email address. If a match is found, the customer is linked automatically and the transfer proceeds as an update instead of a create. Addresses and other child objects of the customer are not linked by that match, and may encounter transfer errors depending on the type of data conflict occurring.
Unmapped Field Overwrite Risk
Transfers TO iPaaS.com are written by the iPaaS.com platform, which replaces the destination record with the values supplied by the mapping collection. An iPaaS.com field that has no mapping in the collection writing it is therefore cleared when the record is updated from HubSpot. This is the opposite of the FROM iPaaS.com direction, where an unmapped HubSpot property is left as it is.
The following fields are not mapped by the default template and are at risk of being cleared on update:
Customer (Add/Update HubSpot Contact TO iPaaS.com): Comment is the only standard Customer field left unmapped, along with any iPaaS.com Customer custom field that has no mapping on this collection.
Customer Relationship (Add/Update HubSpot Contact Association TO iPaaS.com): StartDate, the date the relationship began, and EndDate, the date the relationship ended. HubSpot associations carry no start or end date, so there is no HubSpot value to supply them.
Customer Address (Add/Update HubSpot Contact Address TO iPaaS.com): Type, the address type descriptor; Name, the address name or label; Address2, the second street address line; Address3, the third street address line; and IsPrimaryShipping, whether the address is the customer's primary shipping address.
When using a bi-directional sync, it is important to map all values you wish to be preserved. For example, HubSpot does not have a company email property by default, which poses a risk that the iPaaS.com company email would be removed when the record is updated from HubSpot. To preserve a value that HubSpot cannot supply, add a mapping for that field and use the DestinationValue source, which reads the value already stored on the iPaaS.com record and writes it back unchanged. Subscribers or their MiSP should plan mappings to preserve all necessary values before enabling a bi-directional transfer.
Supported Child Collections
Add/Update HubSpot Contact Address TO iPaaS.com: imports the contact's address into iPaaS.com as part of the contact's transfer. Standard HubSpot contact fields contain a single address entry, so the template mappings write it to the customer's primary billing address.
Add/Update HubSpot Contact Association TO iPaaS.com: imports the contact's company and contact associations into iPaaS.com as Customer Relationships. Each association is only imported once the record that owns it already exists in iPaaS.com.
System Caveats
HubSpot Caveats
Contact properties are read by label: a label-based custom-field mapping resolves the HubSpot property whose label matches the name supplied in the formula, then reads that property's value from the contact. Each such mapping performs its own live property-schema lookup, so keep the number of label-based custom-property mappings to what the subscription actually needs. The HubSpot Owner Id and HubSpot Owner Email mappings do not use a label lookup.
A HubSpot contact holds a single address: only one address is available on the contact record to import. A HubSpot contact cannot carry a separate shipping address alongside a billing address.
Address values are plain text: HubSpot does not validate the address and does not standardize country or state values. Whatever text is present on the contact is what transfers.
Single category property: only one HubSpot property represents the contact category, so a HubSpot contact carries one category value.
Owner resolution: the HubSpot Owner Email mapping resolves the contact's owner id to that owner's email address at transfer time. It returns no value if the owner id is empty or no longer resolves in HubSpot.
Association labels are free-form: HubSpot allows both its own built-in association labels and custom labels defined in the account. The raw label transfers to iPaaS.com exactly as HubSpot supplies it.
One HubSpot pair can carry several associations: the same contact and company can be linked by a basic association and by one or more labelled associations at the same time. Each of these arrives in iPaaS.com as a separate relationship.
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
External-id link required: the HubSpot contact id is saved as the external id so updates edit the same iPaaS.com Customer rather than creating a duplicate.
Unique email: iPaaS.com requires the customer email address to be unique when the record is created.
Customer number is required: iPaaS.com requires a customer number on every Customer create and update. The default template sources it from the HubSpot contact Phone property.
At least one name value is required: iPaaS.com requires at least one of FirstName, LastName, or Company on every Customer create and update. The default template maps all three.
Category lookup: a HubSpot category value is assigned only if it resolves to an iPaaS.com customer category. Values that do not resolve are skipped without raising an error.
Relationship type and related-to id must be unique together: this is why the HubSpot association type is appended to the related-to id, as described under External ID Format.
The related record must exist first: the association child's mapping filter skips a relationship whose owning record has not been transferred and linked yet.
Duplicate address prevention is on: because the duplicate-prevention flag is set on the address child, an address whose values exactly match an existing iPaaS.com address on that customer is not transferred again. A change to any of the mapped values makes the address distinct and it will transfer.
Primary billing is asserted every time: the address mapping sets the primary-billing flag on each transfer, so the imported address is always presented to iPaaS.com as the customer's primary billing address.
Setup Requirements
iPaaS.com Configuration
Configure a scheduled contact/poll event in the iPaaS.com event system using the Webhook (poll request) event type. No automatic transfers occur until a polling schedule is configured.
Create any Customer-module custom fields that label-based custom-field mappings should populate, on the iPaaS.com HubSpot subscription's custom fields page.
Populate the Contact Category Field Name subscription setting if contact categories should transfer. Leaving it empty fully disables category assignment processing and the pre-processing that transfers dependent categories.
HubSpot Configuration
Create the contact category property named in Contact Category Field Name as a Dropdown select property on the Contact object, with at least one category name defined.
Create any Contact object properties that label-based custom-field mappings read, under Settings > Data Management > Properties, before adding the mapping.
Confirm the connected HubSpot account can read contacts, their associations, and their properties.
Authentication and connection setup are covered in HubSpot Installation Instructions and HubSpot Connections and Settings.
Integration Flow
A scheduled contact/poll event, a manually sent contact/poll request, or a manual sync dispatches the contact transfer. A scheduled poll transfers only the contacts modified since the previous poll, using the timestamp saved to the HubSpot subscription after the last polling event.
The HubSpot contact and its mapped properties are retrieved. Any label-based custom-field mapping resolves its HubSpot property by label at this point and reads that property's value from the contact.
The contact's company and contact associations are retrieved, so the relationships travel with the record rather than as a separate lookup.
When the Contact Category Field Name setting is populated, the contact's category value is resolved from the named HubSpot property into an iPaaS.com customer category. A category that already exists in iPaaS.com is linked by name; one that does not is transferred first as a dependent record. Leaving the setting empty skips this step entirely.
The integration resolves whether the HubSpot contact is already linked to an iPaaS.com Customer. When there is no link, iPaaS.com is searched for an existing customer using the same email address; a match is linked automatically and the transfer proceeds as an update rather than a create.
The assembled contact is dispatched to iPaaS.com, where the Customer is created or updated.
The child collections run as part of the same transfer. The address child writes the contact's single address as the customer's primary billing address, skipping it when an identical address already exists on that customer. The association child imports each association whose owning record already exists in iPaaS.com, and skips the rest.
Because the update replaces the iPaaS.com record, only the values the mapping collection supplies survive. Fields left unmapped are cleared — see Unmapped Field Overwrite Risk.
Mappings
Add/Update HubSpot Contact TO iPaaS.com (Parent)
iPaaS.com data type: Customer
This collection reads a HubSpot contact and creates or updates the matching iPaaS.com Customer, linked by the HubSpot contact id saved as the external id. It is the parent of the address and association child collections.
Mapping Type | Source Field (HubSpot) | Destination Field (iPaaS.com) | Description |
Dynamic Formula |
| Job Title | Optional. Looks up the HubSpot contact property whose label is Job Title, resolves it to its internal property name, and writes that property's value to the iPaaS.com Job Title custom field. Most HubSpot contact properties are not exposed as directly selectable source fields, so a formula of this shape is how such a property is brought TO iPaaS.com. The label match is not case-sensitive. If no property carries that label, or the contact has no value for it, the mapping returns no value. The property must already exist in HubSpot under Settings > Data Management > Properties. |
Field | Phone | CustomerNumber | Required. iPaaS.com requires a customer number on every Customer create and update. The default template sources it from the HubSpot contact's Phone property, which gives every incoming contact a value without requiring a dedicated HubSpot property. Subscribers or their MiSP may re-source this mapping to a HubSpot property that carries their own customer numbering scheme; it must continue to supply a value, because iPaaS.com rejects a Customer without one. |
Field | LastName | LastName | Recommended. The HubSpot contact's last name. iPaaS.com requires at least one of FirstName, LastName, or Company on a Customer; this mapping is one of the three that satisfy that requirement. |
Field | EmailAddress | Required. The HubSpot contact's email address, written to the iPaaS.com Customer EmailAddress. iPaaS.com requires an email address on every Customer, and it must be unique when the record is created. This is also the value used to prevent duplicates: a new customer is matched against existing iPaaS.com customers by email, and a match is linked automatically so the transfer proceeds as an update instead of a create. | |
Field | Company | Required. in combination. iPaaS.com requires at least one of FirstName, LastName, or Company on every Customer create and update. HubSpot does not require a contact to have a name, but the integration always supplies an email address — so sourcing Company from Email guarantees the iPaaS.com constraint is satisfied even for a contact with no first or last name, and the transfer succeeds rather than failing validation. Subscribers or their MiSP who maintain a genuine company name on the HubSpot contact may re-source this mapping to that property instead; the mapping should keep supplying a value unless FirstName or LastName is guaranteed to be populated on every contact. | |
Dynamic Formula |
| Interested Sports | Optional. Looks up the HubSpot contact property whose label is Favourite Sports and writes its value to the iPaaS.com Interested Sports custom field. This mapping ships as a worked example of the label-lookup pattern described under Job Title, demonstrating how any HubSpot contact property is brought TO iPaaS.com by its property label; the paired Favourite Sports mapping on Add/Update HubSpot Contact FROM iPaaS.com demonstrates the same field round-tripping back to HubSpot. If no property carries the label, or the contact has no value for it, the mapping returns no value. 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. |
Dynamic Formula |
| Categories | Optional. Converts the HubSpot contact's category values into iPaaS.com customer category assignments, resolving each to its iPaaS.com category id and skipping any that do not resolve. The category values are read from the HubSpot contact property named in the Contact Category Field Name subscription setting, which must be created in HubSpot beforehand as a Dropdown select property on the Contact object. Leaving that setting empty fully disables category assignment processing and the pre-processing that transfers dependent categories. A category that does not resolve is skipped without raising an error. |
Field | HubspotOwnerId | HubSpot Owner Id | Optional. The HubSpot owner id assigned to the contact, retained on the iPaaS.com Customer for reference and for use in later mapping logic. The value is the numeric HubSpot owner identifier, not a name or email address; the paired HubSpot Owner Email mapping resolves it to something human-readable. |
Dynamic Formula |
| HubSpot Owner Email | Optional. Resolves the contact's HubSpot owner id to that owner's email address and writes it to the iPaaS.com HubSpot Owner Email custom field, giving a readable counterpart to the raw owner id. The mapping returns no value if the contact has no owner assigned or the owner id no longer resolves in HubSpot — for example when the owner has been removed from the portal. |
Field | FirstName | FirstName | Recommended. The HubSpot contact's first name. iPaaS.com requires at least one of FirstName, LastName, or Company on a Customer; this mapping is one of the three that satisfy that requirement. |
Add/Update HubSpot Contact Association TO iPaaS.com (Child)
iPaaS.com data type: Customer Relationship
This collection imports a HubSpot association on a contact into an iPaaS.com Customer Relationship, so that the links between people and organizations are preserved alongside the customer record itself. It runs as part of its parent contact's transfer and has no independent trigger of its own.
Mapping Filter
var customerId = await GetSpaceportIdAsync(Id.Split("|")[0], "Customer", SpaceportSystemId);
if(customerId == null || customerId <= 0){
customerId = await GetSpaceportIdAsync(Id.Split("|")[0], "Company", SpaceportSystemId);
if(customerId == null || customerId <= 0)
return false;
}
return true;Filter Description. The filter makes sure a relationship is imported only once the record it belongs to actually exists in iPaaS.com. It takes the first segment of the relationship's id — the id of the HubSpot record that owns the association — and first looks for an iPaaS.com Customer linked to that HubSpot id. If a linked Customer is found, the filter passes and the relationship is imported. If no linked Customer is found, the filter looks for an iPaaS.com Company linked to the same HubSpot id, and the relationship is imported if one is found. If neither a linked Customer nor a linked Company is found, the filter does not pass and the relationship is skipped. A skipped relationship is not an error: nothing is written and no entry appears in the Error Logs. In practice, a relationship is skipped when the record it points at has not been transferred to iPaaS.com yet, and it imports normally on the next transfer of the parent contact once that contact or company has transferred and is linked.
It is not advised to alter the existing mappings in this collection. They are required to support HubSpot associations, and changing them can break the link between the two systems. Subscribers or their MiSP may safely add mappings to iPaaS.com Relationship custom fields to capture more information about the relationship.
Mapping Type | Source Field (HubSpot) | Destination Field (iPaaS.com) | Description |
Field | IsPrimary | IsPrimary | Whether HubSpot treats this association as the primary one for the record — for example, a contact's primary company. Optional: the iPaaS.com Customer Relationship does not require it. Mapping it keeps the primary designation aligned between the two systems, so it is worth leaving in place. |
Field | RelationshipType | Customer Relationship Type | The raw association label exactly as HubSpot supplies it, stored on an iPaaS.com Relationship custom field. Optional: nothing in the transfer depends on it. It is included in the template as a worked example of mapping association information to a Relationship custom field, and because it keeps the original HubSpot label visible in iPaaS.com where it can be used in mapping logic at a later point. This differs from the Type mapping in this table, which writes the HubSpot relationship type rather than the raw label. |
Dynamic Formula |
| Type | The relationship type in iPaaS.com, taken from the HubSpot relationship type. The formula capitalizes the first letter of the HubSpot value and leaves the rest of it exactly as HubSpot supplied it, so a HubSpot type reads as a tidy label in iPaaS.com without otherwise being reinterpreted. Recommended: the iPaaS.com API does not require a type, but the type forms half of the uniqueness requirement for a relationship — iPaaS.com requires a unique combination of relationship type and related-to id — so leaving it empty is not advised. Note this reads the HubSpot relationship type rather than the raw association label; the raw label is captured separately by the Customer Relationship Type custom field mapping in this table. |
Dynamic Formula |
| RelatedToId | Required. The iPaaS.com record this relationship points at. |
Dynamic Formula |
| Name | A readable label for the relationship, stored on an iPaaS.com Relationship custom field. The formula uses the associated company's name when the association came from a Company, and falls back to the associated contact's first name when it came from a Customer. Optional: it exists to make the relationship recognizable at a glance rather than to drive any behavior. This mapping also illustrates which fields are available to map from, since that depends on the source record of the association. From a Customer association: CustomerFirstName, CustomerLastName, CustomerEmail. From a Company association: CompanyName, CompanyDomain. Available on both: RelationshipType, ReadOnlyRelationshipType, Archived, CustomerCompanyCreatedate, CustomerCompanyLastModifiedDate, and CustomerCompanyHsObjectId. |
RelatedToId
The iPaaS.com record this relationship points at. This value is required — the iPaaS.com Customer Relationship API requires a related-to id on every relationship.
The formula takes the HubSpot record the association points at and resolves it to the linked iPaaS.com record: it looks first for a linked Customer, and falls back to a linked Company when no Customer is linked. It then appends the HubSpot association type to the resolved id, separated by a pipe character.
That append is deliberate and is central to how HubSpot associations are represented in iPaaS.com. A single iPaaS.com relationship can produce more than one HubSpot association on the same pair of records, because HubSpot supports both basic association links and additional association labels. If the original related-to id were kept unchanged, those extra associations would collide on the iPaaS.com requirement for a unique relationship type and related-to id combination, and would raise a duplicate error on their way back. Appending the association type gives each HubSpot association its own distinct iPaaS.com relationship.
Two consequences are worth planning for. Other integrations consuming this relationship data must account for this related-to id format in their own transfers. And subscribers or their MiSP who do not want every association type to transfer can use mapping collection filters to control which ones do. Consult your MiSP for assistance with either.
Add/Update HubSpot Contact Address TO iPaaS.com (Child)
iPaaS.com data type: Customer Address
This collection imports the single address held on a HubSpot contact into an iPaaS.com Customer Address as the customer's primary billing address. It runs as part of its parent contact's transfer and has no independent trigger of its own.
Two control fields shape how the address is written, and both are set deliberately by the template. IsPrimaryBilling is set so the imported address lands as the customer's primary billing address in iPaaS.com, which matches the way the opposite-direction Contact collection reads the address back out of iPaaS.com, so an address that round-trips returns to the same place on the HubSpot contact. PreventDuplicate is set so iPaaS.com does not transfer the address when all of the requested address values already exist as an iPaaS.com address on that customer, which keeps repeated contact transfers from stacking up duplicate address records.
Mapping Type | Source Field (HubSpot) | Destination Field (iPaaS.com) | Description |
Dynamic Formula |
| LastName | The recipient last name on the address, read from the parent HubSpot contact, for the same reason as FirstName. Optional — the iPaaS.com Customer Address does not require it. |
Dynamic Formula |
| FirstName | The recipient first name on the address, read from the parent HubSpot contact. A standard HubSpot contact holds a single address with no separate recipient name, so the contact's own name is used. Optional — the iPaaS.com Customer Address does not require it. Change this mapping if a different value should appear as the address recipient. |
Dynamic Formula |
| Address1 | The primary street address line, read from the parent HubSpot contact's Address property. Recommended: the iPaaS.com Customer Address accepts a record without a street line, but an address is not usable downstream without one. HubSpot does not validate the value, so it transfers exactly as entered. |
Dynamic Formula |
| Region | The HubSpot State value, written to the iPaaS.com Region. Recommended for a usable address record. HubSpot does not standardize state or province values, so whatever text is on the contact is what transfers — subscribers or their MiSP who need a consistent format should plan for that in their mappings. |
Dynamic Formula |
| City | The city on the parent HubSpot contact's address. Recommended for a usable address record; the iPaaS.com Customer Address does not require it. |
Dynamic Formula |
| Country | The country on the parent HubSpot contact's address. Recommended for a usable address record. As with Region, HubSpot does not standardize the value. |
Static |
| PreventDuplicate | A control flag, set deliberately by the template. It tells iPaaS.com not to transfer the address when all of the requested address values already exist as an iPaaS.com address on that customer. Because a HubSpot contact's address transfers every time the contact does, this flag is what stops repeated contact transfers from stacking up duplicate address records. It is not a data field and it does not appear on the finished address. When an address is skipped for this reason, nothing is written and no error is raised. Recommended: leave this set. |
Dynamic Formula |
| IsPrimaryBilling | A control flag, set deliberately by the template so the imported address becomes the customer's primary billing address in iPaaS.com. This is by design, not a value awaiting configuration: a standard HubSpot contact holds only one address, so the template treats that address as the contact's primary billing address. It also matches the opposite direction — when a customer transfers from iPaaS.com to HubSpot, the primary billing address is the one read back onto the contact's address fields, so an address that round-trips returns to the same place. Recommended: leave this set unless you are deliberately building a different address model, and consult your MiSP before changing it. |
Dynamic Formula |
| PostalCode | The HubSpot Zip value, written to the iPaaS.com PostalCode. Recommended for a usable address record; the iPaaS.com Customer Address does not require it. |
Dynamic Formula |
| Company | The company name carried on the address as free text, read from the parent HubSpot contact's Company property. This is the address's own company line and is separate from any structured company relationship on the customer. Optional. |
Dynamic Formula |
| PhoneNumber | The phone number on the parent HubSpot contact, carried onto the address. Optional — the iPaaS.com Customer Address does not require it. Note that the parent Customer collection also maps the contact's Phone to the iPaaS.com CustomerNumber, so the same HubSpot value serves two purposes; this mapping is what puts the phone number on the address itself. |
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 imports are:
HubSpot API Communication: covers the messages raised when HubSpot rejects or cannot serve a contact read, 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.
Customer validation errors: raised when iPaaS.com rejects the Customer write — most commonly a missing customer number, a missing email address, an email address that is not unique on a create, or none of FirstName, LastName, or Company carrying a value. Correct the source values on the HubSpot contact, or adjust the mappings that supply them, then re-sync the contact.
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 defined. Correct the property in HubSpot, or clear the setting to disable category processing, then re-sync the contact.
Errors are reported under Dashboard, Integration Monitoring, Error Logs. A relationship skipped by the association child's mapping filter, and an address skipped by duplicate prevention, are not errors and produce no entry there.
Testing & Validation
Test Scenarios
Create a new HubSpot contact that has never been transferred, giving it an email address and a phone number, then manually sync it by its HubSpot contact id. Confirm a new iPaaS.com Customer is created and that it carries the HubSpot contact id as its external-id link.
Change the first name or email address on that same HubSpot contact and re-sync. Confirm the existing iPaaS.com Customer is updated in place and no second Customer appears.
Create a HubSpot contact whose email address matches an existing, unlinked iPaaS.com Customer, then sync it. Confirm the existing Customer is linked and updated rather than a duplicate being created.
Configure a scheduled contact/poll event using the Webhook (poll request) event type. Modify a contact in HubSpot, wait for the next poll, and confirm only contacts modified since the previous poll are transferred.
Populate the address fields on a HubSpot contact and re-sync. Confirm the address arrives on the iPaaS.com Customer as the primary billing address. Re-sync without changing anything and confirm no second, identical address is created. Change the city and re-sync, and confirm the changed address transfers.
Associate the HubSpot contact with a company that has not been transferred to iPaaS.com, then sync. Confirm the relationship is skipped without an error. Transfer the company, re-sync the contact, and confirm the relationship is created.
Link the same HubSpot contact and company with both a basic association and a labelled association. Confirm each arrives in iPaaS.com as its own distinct Customer Relationship rather than raising a duplicate error.
Create a Contact object property in HubSpot, create the matching Customer-module custom field in iPaaS.com, add a label-based Dynamic Formula mapping between them, and re-sync. Confirm the value reaches the iPaaS.com custom field. Change the property label in HubSpot without updating the mapping and confirm the mapping returns no value.
Populate the Contact Category Field Name setting with a valid HubSpot Dropdown select property, set a category value on the contact, and re-sync. Confirm the category assignment appears on the iPaaS.com Customer. Clear the setting and confirm category processing stops with no error raised.
Put a value in the Comment field on a linked iPaaS.com Customer, then re-sync the contact from HubSpot. Confirm the value is cleared, then add a Comment mapping using the DestinationValue source and confirm the value survives the next transfer.
Validation Checklist
A first transfer creates an iPaaS.com Customer and records the external-id link.
A second transfer of the same contact updates it rather than creating a duplicate.
A contact whose email address matches an existing iPaaS.com Customer links to that Customer instead of creating one.
Fields left unmapped on the iPaaS.com Customer, Customer Relationship, and Customer Address are cleared on update unless a DestinationValue mapping preserves them.
The contact's address arrives as the primary billing address, and an identical repeat address is not duplicated.
Relationships appear only once the record that owns the association exists in iPaaS.com.
Each HubSpot association on the same pair of records arrives as its own iPaaS.com relationship.
Only contacts modified since the previous poll are transferred by a scheduled poll.
Errors appear under Dashboard, Integration Monitoring, Error Logs.
Additional Notes
At the time this documentation was written, HubSpot contacts do not transfer to iPaaS.com automatically through webhooks. A scheduled contact/poll event must be configured, and only contacts modified since the previous poll are transferred.
At the time this documentation was written, when an incoming contact is matched to an existing iPaaS.com Customer 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, the HubSpot association type is appended to the related-to id in order to satisfy the iPaaS.com requirement that relationship type and related-to id be unique together. Other integrations that consume this relationship data must account for that id format in their own transfers. Subscribers or their MiSP can use mapping collection filters to prevent unwanted association types from transferring; consult your MiSP for assistance adjusting relationship mappings or building these filters.
At the time this documentation was written, because a HubSpot contact holds a single address, only one iPaaS.com Customer Address per contact can be maintained through these collections.
At the time this documentation was written, HubSpot custom properties are not available as a source on either child collection. Custom-property mapping for a contact is available on the parent collection instead.
HubSpot companies are imported by the separate HubSpot Company collections, not by these collections. Relationships between objects other than contacts and companies are not handled.
Products, orders, and line items have their own collections.
Address validation or standardization is not performed by either system during transfer.
Writing iPaaS.com customers to HubSpot is handled by Add/Update HubSpot Contact FROM iPaaS.com, the opposite-direction collection.