Overview
The Klaviyo integration provides a set of ready-made functions you can call when building mappings. They handle common lookups and conversions for Klaviyo, such as finding a Klaviyo profile by email or phone number, formatting a phone number to Klaviyo's expected format, reading custom field and address values from an iPaaS.com customer, and pulling a value from deep inside a nested payload, 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 Klaviyo 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 Klaviyo account and your iPaaS.com subscription.
The functions are grouped below by the area of the integration they support.
Customers
Use these to look up a Klaviyo profile by email or phone number.
GetCustomerIdByEmail
What it does: Looks up a Klaviyo profile by email address and returns its Klaviyo profile ID. Returns nothing if no profile matches.
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 Klaviyo by. |
Returns: string. The Klaviyo profile ID, or nothing if no profile matches.
Example: await GetCustomerIdByEmail("john.doe@example.com") returns the Klaviyo profile ID for that email.
When to use it: When mapping a record to a Klaviyo profile and you have the customer's email but need the Klaviyo profile ID.
GetCustomerByEmail
What it does: Looks up a Klaviyo profile by email address and returns the full profile search response. Returns an empty response if the lookup fails.
Signature: Task<object> GetCustomerByEmail(object emailAddress)
How to call it: await GetCustomerByEmail(emailAddress)
Parameter | Type | Required | Default | Description |
emailAddress |
| Yes | N/A | The iPaaS.com customer email address used for the Klaviyo lookup. |
Returns: object. The Klaviyo profile search response, or an empty response if the lookup fails.
Example: await GetCustomerByEmail("ali@example.com") returns the Klaviyo profile record for that email.
When to use it: When you need the full Klaviyo profile details for an email, not just the ID.
GetCustomerIdByPhoneNumber
What it does: Formats a phone number to Klaviyo's expected format, looks up the matching Klaviyo profile, and returns its Klaviyo profile ID. Returns nothing if the number cannot be formatted or no profile matches.
Signature: Task<string> GetCustomerIdByPhoneNumber(object phoneNumber)
How to call it: await GetCustomerIdByPhoneNumber(phoneNumber)
Parameter | Type | Required | Default | Description |
phoneNumber |
| Yes | N/A | The iPaaS.com customer phone number (may include non-digit characters). |
Returns: string. The Klaviyo profile ID, or nothing if the number cannot be formatted or no profile matches.
Example: await GetCustomerIdByPhoneNumber("+1-123-456-7890") returns the Klaviyo profile ID for that phone number.
When to use it: When mapping a record to a Klaviyo profile and you have the customer's phone number but need the Klaviyo profile ID.
GetCustomerByPhoneNumber
What it does: Looks up a Klaviyo profile by a formatted, URL-encoded phone number and returns the full profile search response. Returns an empty response if the lookup fails.
Signature: Task<object> GetCustomerByPhoneNumber(object phoneNumber)
How to call it: await GetCustomerByPhoneNumber(phoneNumber)
Parameter | Type | Required | Default | Description |
phoneNumber |
| Yes | N/A | The phone number to search by, already formatted for Klaviyo and URL-encoded (including the surrounding quotes). Use |
Returns: object. The Klaviyo profile search response, or an empty response if the lookup fails.
Example: await GetCustomerByPhoneNumber(phoneNumber) returns the Klaviyo profile record for that phone number.
When to use it: When you need the full Klaviyo profile details for a phone number that is already formatted and URL-encoded. To start from a raw phone number, use GetCustomerIdByPhoneNumber instead.
Phone Numbers
Use this to prepare a phone number in Klaviyo's expected format.
GetKlaviyoFormattedPhoneNumber
What it does: Formats a raw phone number into Klaviyo's expected format by removing non-digit characters and applying country-code rules (supports the US, Canada, UK, Australia, and Ireland). Returns nothing if the number cannot be formatted.
Signature: string GetKlaviyoFormattedPhoneNumber(object phone_number)
How to call it: GetKlaviyoFormattedPhoneNumber(phone_number)
Parameter | Type | Required | Default | Description |
phone_number |
| Yes | N/A | The raw iPaaS.com customer phone number (may include punctuation). |
Returns: string. The phone number in Klaviyo's format (prefixed with +), or nothing if it cannot be formatted.
Example: GetKlaviyoFormattedPhoneNumber("001-123-456-7890") returns a value such as "+11234567890".
When to use it: When mapping a phone number to Klaviyo and you need it in Klaviyo's expected format.
Custom Fields and Values
Use these to read custom fields, address values, and nested values from an iPaaS.com customer's data.
GetValueFromCustomField
What it does: Reads a single custom field value from an iPaaS.com customer's custom fields, matching the field by name. Field names are matched loosely, ignoring case and punctuation. Returns nothing if the field is not found.
Signature: Task<object> GetValueFromCustomField(object customFieldObj, object textFieldName)
How to call it: await GetValueFromCustomField(customFieldObj, textFieldName)
Parameter | Type | Required | Default | Description |
customFieldObj |
| Yes | N/A | The iPaaS.com customer's custom fields to read from. |
textFieldName |
| Yes | N/A | The custom field name to look up. Case and punctuation are ignored. |
Returns: object. The custom field's value, or nothing if the field is not found.
Example: await GetValueFromCustomField(customFields, "First Name") returns "John" for a field named First Name.
When to use it: When mapping a value out of an iPaaS.com customer's custom fields.
GetPropertiesFromCustomFields
What it does: Converts an iPaaS.com customer's custom fields into a set of name/value pairs, keeping only entries whose name and value are both present. The subscribeprofile field, and any field whose name contains list_, are skipped. Returns nothing if the input is empty or has no valid fields.
Signature: object GetPropertiesFromCustomFields(object customFieldObj)
How to call it: GetPropertiesFromCustomFields(customFieldObj)
Parameter | Type | Required | Default | Description |
customFieldObj |
| Yes | N/A | The iPaaS.com customer's custom fields (a list of entries, each with a name and value). |
Returns: object. The custom fields as name/value pairs, or nothing if the input is empty or has no valid fields.
Example: GetPropertiesFromCustomFields(customFieldObj) returns pairs such as CustomerType = "Premium".
When to use it: When mapping an iPaaS.com customer's custom fields to Klaviyo profile properties.
GetValueFromList
What it does: Reads a named property (for example city) from an iPaaS.com customer's address list, choosing the billing or shipping address by the flags you pass. If no address matches, the first address is used. Returns an empty string if the value is not found.
Signature: Task<string> GetValueFromList(object addressListData, string propertyName, bool isBilling = false, bool boolValue = false)
How to call it: await GetValueFromList(addressListData, propertyName)
Parameter | Type | Required | Default | Description |
addressListData |
| Yes | N/A | The iPaaS.com customer's list of addresses. |
propertyName |
| Yes | N/A | The address property to read (for example |
isBilling |
| No |
| When |
boolValue |
| No |
| The value the chosen primary flag (billing or shipping) must equal for an address to be selected. |
Returns: string. The requested property value, or an empty string if it is not found.
Example: await GetValueFromList(addresses, "City", isBilling: false, boolValue: true) returns the city of the primary shipping address.
When to use it: When mapping a value from an iPaaS.com customer's billing or shipping address to Klaviyo.
GetValueByPath
What it does: Reads a value from a nested object or JSON structure using a dot-separated path. When the path lands on a list, you can pull one property from each item and either return a specific index or join the values. Returns nothing if the path does not resolve.
Signature: object? GetValueByPath(object obj, string path, string listItem = null, string indexOrSeparator = null)
How to call it: GetValueByPath(obj, path)
Parameter | Type | Required | Default | Description |
obj |
| Yes | N/A | The object or JSON structure to read from. |
path |
| Yes | N/A | The dot-separated property path (for example |
listItem |
| No |
| When the path resolves to a list, the property to read from each item (for example |
indexOrSeparator |
| No |
| When reading from a list: a number returns the item at that index; any other text is used as the separator to join the values. A comma is used when omitted. |
Returns: object. The value at the path, or the selected or joined list values; nothing if the path does not resolve.
Example: GetValueByPath(subscriptions, "email.marketing.suppression", "Reason") returns the joined reasons, such as "HARD_BOUNCE,HARD_BOUNCE 2".
When to use it: When mapping a value from deep inside a nested payload, or pulling a value from a list within it.