Overview
The HubSpot integration provides a set of ready-made functions you can call when building mappings. They handle common lookups and conversions for HubSpot, such as finding a contact, product, owner, or lifecycle stage by a value you already have, reading a value out of a HubSpot record, or converting category data between HubSpot and iPaaS.com, so you don't have to write that logic yourself.
Where you can use these functions
These functions are available anywhere you write a formula for the HubSpot integration:
Dynamic Formula mappings: where a destination field's value is produced by a formula rather than mapped directly from a source field.
Mapping collection filters: where a formula decides whether a record should be processed.
Error filters: a mapping collection's error filter, which sits alongside its collection filter. When the error filter's formula resolves to true, the transfer raises an error that is held in the Error Logs for review and is not retried automatically.
Translation collections: where a translation entry uses a formula as its source value.
How to use them
Call a function by name and pass the values it needs in parentheses, for example:
await GetCustomerIdByEmail(emailAddress).Each function's signature shows its name, the parameters it accepts (with their types), and the type of value it returns. Use it as the reference for exactly how to call the function.
Function names and formula syntax are case-sensitive, so type each name exactly as shown. Whether the values a function matches are treated as case-sensitive varies by function, and is called out in the relevant parameter's description.
Some of these functions are asynchronous (their signature returns a
Task) and must be called withawait; the rest are synchronous and are called directly. Each function's How to call it example shows the correct form.Optional parameters are marked in the parameter table, along with the value used when you omit them.
Each function runs at sync time, against the data in your connected HubSpot account and your iPaaS.com subscription.
The functions are grouped below by the area of the integration they support.
Customers and Contacts
Use these when looking up a HubSpot contact or reading values out of a HubSpot customer record during mapping.
GetCustomerIdByEmail
What it does: Looks up a HubSpot contact by email address and returns its HubSpot contact ID. Returns nothing if no matching contact is found.
Signature: Task<string> GetCustomerIdByEmail(object emailAddress)
How to call it: await GetCustomerIdByEmail(emailAddress)
Parameter | Type | Required | Default | Description |
emailAddress |
| Yes | N/A | The iPaaS.com customer email address to search HubSpot contacts by. |
Returns: string. The HubSpot contact ID, or nothing if no contact matches the email.
Example: await GetCustomerIdByEmail("user@example.com") returns the HubSpot contact ID for that email.
When to use it: When mapping a record to a HubSpot contact and you have the customer's email but need the HubSpot contact ID.
GetLifeCycleStageIdByName
What it does: Looks up a HubSpot contact lifecycle stage by its name and returns the matching lifecycle stage ID. Returns nothing if no stage matches. The match is not case-sensitive.
Signature: Task<string> GetLifeCycleStageIdByName(string name)
How to call it: await GetLifeCycleStageIdByName(name)
Parameter | Type | Required | Default | Description |
name |
| Yes | N/A | The iPaaS.com lifecycle stage name to match against HubSpot lifecycle stages (for example |
Returns: string. The HubSpot lifecycle stage ID, or nothing if no stage matches.
Example: await GetLifeCycleStageIdByName("customer") returns the lifecycle stage ID for the "customer" stage.
When to use it: When mapping a contact's lifecycle stage to HubSpot and your source provides the stage name rather than its ID.
GetValueFromProperties
What it does: Reads a single property value from a HubSpot record's properties, looking the property up by its label for the given HubSpot model. Returns an empty string if the property is not found.
Signature: Task<string> GetValueFromProperties(object propertiesDict, string propertyName, string Model)
How to call it: await GetValueFromProperties(propertiesDict, propertyName, Model)
Parameter | Type | Required | Default | Description |
propertiesDict |
| Yes | N/A | The HubSpot record's properties object to read from. |
propertyName |
| Yes | N/A | The label of the HubSpot property to retrieve (for example |
Model |
| Yes | N/A | The HubSpot model the property belongs to (for example |
Returns: string. The requested property value, or an empty string if the property is not found.
Example: await GetValueFromProperties(propertiesDict, "email", "contact") returns the contact's email value.
When to use it: When mapping a value out of a HubSpot record's properties and you know the property's label and model.
GetValueFromAddressList
What it does: Reads a named property (for example city or state) from a HubSpot customer address list, choosing between billing and shipping addresses and between primary and non-primary addresses. Returns an empty string if the value is not found.
Signature: Task<string> GetValueFromAddressList(object addressListData, string propertyName, bool isBilling = false, bool boolValue = false)
How to call it: await GetValueFromAddressList(addressListData, propertyName)
Parameter | Type | Required | Default | Description |
addressListData |
| Yes | N/A | The HubSpot customer address list to read from. |
propertyName |
| Yes | N/A | The property name to extract (for example |
isBilling |
| No |
| When |
boolValue |
| No |
| When |
Returns: string. The requested property value, or an empty string if it is not found.
Example: await GetValueFromAddressList(addresses, "city", isBilling: true) returns the city from the billing address.
When to use it: When mapping a value from a HubSpot customer's billing or shipping address into an iPaaS.com field.
Owners
Use these to translate between a HubSpot owner's ID and their email address.
GetOwnerIdByEmail
What it does: Looks up a HubSpot owner by email address and returns the owner's ID. Returns nothing if no owner matches.
Signature: Task<string> GetOwnerIdByEmail(string email)
How to call it: await GetOwnerIdByEmail(email)
Parameter | Type | Required | Default | Description |
| Yes | N/A | The HubSpot owner's email address to look up. |
Returns: string. The HubSpot owner ID, or nothing if no owner matches.
Example: await GetOwnerIdByEmail("owner@example.com") returns the HubSpot owner ID for that email.
When to use it: When assigning ownership on a HubSpot record and you have the owner's email but need the HubSpot owner ID.
GetOwnerEmailById
What it does: Returns a HubSpot owner's email address for a given HubSpot owner ID. Returns nothing if the owner is not found.
Signature: Task<string> GetOwnerEmailById(string ownerId)
How to call it: await GetOwnerEmailById(ownerId)
Parameter | Type | Required | Default | Description |
ownerId |
| Yes | N/A | The HubSpot owner ID to look up. |
Returns: string. The HubSpot owner's email address, or nothing if the owner is not found.
Example: await GetOwnerEmailById("12345") returns the email address of that HubSpot owner.
When to use it: When you have a HubSpot owner ID and need the owner's email address during mapping.
Products
Use these when translating between product SKUs, IDs, and descriptions across HubSpot and iPaaS.com.
GetProductIdBySku
What it does: Looks up a HubSpot product by SKU and returns its HubSpot product ID. Returns nothing if no product matches.
Signature: Task<string> GetProductIdBySku(object sku)
How to call it: await GetProductIdBySku(sku)
Parameter | Type | Required | Default | Description |
sku |
| Yes | N/A | The iPaaS.com product SKU to search HubSpot products by. |
Returns: string. The HubSpot product ID, or nothing if no product matches the SKU.
Example: await GetProductIdBySku("ABC-123") returns the HubSpot product ID for that SKU.
When to use it: When mapping a line or product reference to HubSpot and you have the product SKU but need the HubSpot product ID.
GetiPaaSProductSkuById
What it does: Returns the SKU of an iPaaS.com product for a given iPaaS.com product ID. Returns nothing if the product has no SKU or is not found.
Signature: Task<string> GetiPaaSProductSkuById(string productId)
How to call it: await GetiPaaSProductSkuById(productId)
Parameter | Type | Required | Default | Description |
productId |
| Yes | N/A | The iPaaS.com product ID to look up. |
Returns: string. The iPaaS.com product SKU, or nothing if the product has no SKU or is not found.
Example: await GetiPaaSProductSkuById("1001") returns the SKU for that iPaaS.com product.
When to use it: When mapping a product reference and you have the iPaaS.com product ID but need its SKU.
GetiPaaSProductDescriptionById
What it does: Returns the description of an iPaaS.com product for a given iPaaS.com product ID. Returns nothing if the product has no description or is not found.
Signature: Task<string> GetiPaaSProductDescriptionById(string productId)
How to call it: await GetiPaaSProductDescriptionById(productId)
Parameter | Type | Required | Default | Description |
productId |
| Yes | N/A | The iPaaS.com product ID to look up. |
Returns: string. The iPaaS.com product description, or nothing if the product has no description or is not found.
Example: await GetiPaaSProductDescriptionById("1001") returns the description for that iPaaS.com product.
When to use it: When mapping product details to HubSpot and you have the iPaaS.com product ID but need its description.
Customer Categories
Use these to convert customer category data between HubSpot and iPaaS.com.
ConvertHubSpotCategoryToiPaaS
What it does: Converts a HubSpot customer category list into iPaaS.com customer categories, matching each HubSpot category to its iPaaS.com category ID. Categories without a match are skipped.
Signature: Task<object> ConvertHubSpotCategoryToiPaaS(object categories)
How to call it: await ConvertHubSpotCategoryToiPaaS(categories)
Parameter | Type | Required | Default | Description |
categories |
| Yes | N/A | The HubSpot customer category data to convert. |
Returns: object. A list of iPaaS.com customer categories, each carrying its iPaaS.com category ID and name. Returns an empty list when there is nothing to convert.
Example: await ConvertHubSpotCategoryToiPaaS(categories) returns the iPaaS.com customer categories that match the supplied HubSpot categories.
When to use it: When mapping HubSpot customer categories into iPaaS.com during a transfer into iPaaS.com.
GetHubSpotCategoryValuesFromCategories
What it does: Takes an iPaaS.com customer category list and returns the category values for the categories that are mapped to HubSpot. Categories without a HubSpot mapping are skipped.
Signature: Task<List<CustomerCategory>> GetHubSpotCategoryValuesFromCategories(object categories)
How to call it: await GetHubSpotCategoryValuesFromCategories(categories)
Parameter | Type | Required | Default | Description |
categories |
| Yes | N/A | The iPaaS.com customer category data to read from. |
Returns: List<CustomerCategory>. The customer categories whose iPaaS.com category is mapped to HubSpot, each carrying its category value. Returns nothing when the input is empty.
Example: await GetHubSpotCategoryValuesFromCategories(categories) returns the category values for the iPaaS.com categories that are mapped to HubSpot.
When to use it: When mapping iPaaS.com customer categories out to HubSpot during a transfer from iPaaS.com.
Webhook Events
Use this when reading the incoming HubSpot webhook payload that triggers a transfer.
GetScopeOrExternalId
What it does: Scans a batch of HubSpot webhook event objects, keeps only those whose subscription type matches one of the allowed types, and returns a single value from the best-matching event: either its subscription type or the ID of the HubSpot object it refers to. Events that represent a record creation are preferred; if none is present, the first matching event is used. Returns nothing if no event matches.
Signature: string GetScopeOrExternalId(List<object> payloadList, List<string> allowedSubscriptionTypes, bool scope)
How to call it: GetScopeOrExternalId(payloadList, allowedSubscriptionTypes, scope)
Parameter | Type | Required | Default | Description |
payloadList |
| Yes | N/A | The list of HubSpot webhook event objects to scan. Each event carries a subscription type and the ID of the HubSpot object it refers to. |
allowedSubscriptionTypes |
| Yes | N/A | The subscription types to keep. An event is kept when its subscription type contains one of these values. |
scope |
| Yes | N/A | When |
Returns: string. The subscription type of the selected event when scope is true, or the HubSpot object ID when scope is false. Returns nothing when no event matches.
Example: GetScopeOrExternalId(payloadList, allowedSubscriptionTypes, false) returns the HubSpot object ID of the preferred creation event.
When to use it: When processing a HubSpot webhook payload that may contain several events and you need either the subscription type or the object ID of the most relevant event.